@credenza-web3/passport v6.0.0-alpha.2

Credenza3 Passport

Installation

with npm

npm install ethers
npm install @credenza-web3/passport

with yarn

yarn add ethers
yarn add @credenza-web3/passport

with pnpm

pnpm install ethers
pnpm install @credenza-web3/passport

or include a script tag

<script src="https://cdnjs.cloudflare.com/ajax/libs/ethers/6.0.8/ethers.umd.min.js" integrity="sha512-B/0gQMZc/py0Ldqgnuen4yZzABN1sz6dv65+2pVQHgOlIcrshSTJsk7yCSWqh0wh94KUD4Lr5F4HSWzcZjhqqw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<script src="https://cdn.jsdelivr.net/npm/@credenza-web3/passport/dist/passport.umd.js"></script>
<script>
  const Passport = window.CredenzaPassport
</script>

or with esm

<script type="importmap">
  {
    "imports": {
      "ethers": "https://cdn.jsdelivr.net/npm/ethers@6.0.8/+esm"
    }
  }
</script>
<script type="module">
  import {Passport} from 'https://cdn.jsdelivr.net/npm/@credenza-web3/passport/+esm'
</script>

Usage

Create the Passport instance

const passport = new Passport({
  chainId: Passport.chains.GOERLI,
  config: {
    nav?: {
      theme?: Passport.themes.BLACK,
      direction?: Passport.navDirections.BOTTOM,
    },
    content?: {
      cloak?: boolean
      // depends on `cloak: true`
      payPerArticle?: [
        {
          nfts: [{address: 'contract-address-1', tokens:['token-id-1', 'token-id-2'], type: 'ERC1155' | 'ERC721'}],
          memberships: [{address: 'contract-address-1', owner: 'owner-address-1'}],
          uriMasks: ['part-of-the-article-uri'] // [''] for all uris
        }
      ],
      imageUrl?: 'https://yoursite.com/image.png', // Replaces default `Standford Socker` image
      signin: {
        title: "Your title!", // Replaces default ``
        description: "Your description.", // Replaces default ``
      },
      signup: {
        title: "Your title!", // Replaces default ``
        description: "Your description.", // Replaces default ``
      },
      logout: {
        title: "Your title!", // Replaces default ``
        description: "Your description!", // Replaces default ``
      },
      paymentResult?: {
        title?: "Your title!", // Replaces default `Success!`
        subtitle?: "Your subtitle!", // Replaces default `Your payment was successful!`
        description?: "Your description!", // Replaces default `Usually it takes us as many as a few minutes to deliver tokens to your account.`
      }
      progressVideos?: [{
        embedded: true,
        src: 'https://www.youtube.com/embed/tgbNymZ7vqY',
      }, {
        src: 'https://media.w3.org/2010/05/sintel/trailer.mp4'
      }]
    },
    metamask?: {
      disabled?: false,
    },
    magic?: {
      disabled?: false,
    },
    socialLogin?: {
      google?: {
        disabled: false
      }
    },
    auth?: {
      extendedRegistration: false,
    },
    buyTokens?: {
      disabled?: false,
    },
    email?: {
      templateId?: string // For custom email template usage
    }
  },
})

await passport.init()

Passport instance Properties

isLoggedIn: boolean

chainId: string

ethers: Ethers.js https://docs.ethers.io/v5/

user: User instance

Passport static properties

Passport.version (string) Current package version

Passport.chains (enum) Supported chains

Passport.loginProviders (enum) Supported login providers

Passport.pages = (enum) Available pages for logged in User

Passport.paymentTypes = (enum) Available payment types

Passport.themes = (enum) Available color schemas

Passport.navDirections = (enum) Available directions where passport nav bar will expand when opened

Passport.navMinimizationTogglerPositions = (enum) Available minimization toggler positions

Modes

Passport can be used in 3 modes: Code UI Navigation

Apple Pay

You must verify your domain. https://support.stripe.com/questions/enable-apple-pay-on-your-stripe-account Enabled by default on all supported devices and registered domains.

Google Pay

Is enabled on all supported devices by default

Code mode

Login

const params = ['metamask'] || ['magicLink', {email:string}] || ['magicSms', {phone: string}]
const user = await passport.login(...params)

Logout

await passport.logout()

Get ethers provider

await passport.getWeb3Provider():Promise<EthersRPCProvider> // returns Ethers provider

Get current session address

await passport.getAddress():Promise<string | null>

Check membership

await passport.checkMembership(ownerAddress:string):Promise<{isMember:boolean, meta: unknown}>

Get current user roles

await passport.getRoles():Promise<(Admin | Superadmin | User)[]>

Get current user NFTs

await passport.getNfts():Promise<({
  amount: number
  contract_type: string // e.g. "ERC721"
  name: string
  symbol: string
  token_address: string
  token_id: string
  token_uri: string
})[]>

Get CRED Contract

await passport.getCREDContract():Promise<({
  address: string
  decimals: number
  contract: ethers.Contract
})>

Send CRED Stored Value

Do not pass contract if you transfer the native network tokens.

await passport.sendTokens(address: string, amount: string | bigint, contract?: ethers.Contract):Promise<any>

Send Credenza NFT

await passport.sendNft(contract: ethers.Contract, recipient: string, tokenId: string, amount: number):Promise<any>

Request AirDrop

await passport.requestAirDrop({ contractAddress, tokenId, amount, targetAddress }: {
  targetAddress: string
  contractAddress: string
  tokenId?: string | number // tokenId can be skipped if we need to airdrop erc721
  amount?: number // if amount is skipped - default is 1
}):Promise<void>

Request Loyalty Points

await passport.requestLoyaltyPoints(eventId: string, contractAddress: string):Promise<void>

Send email / phone number confirmation code

await passport.sendConfirmation({phone?:string, email?:string}):Promise<boolean>

Confirm email / phone number

await passport.confirmAccount({phoneCode?:number, emailCode?:number}):Promise<boolean>

Navigation mode

Show navigation panel

await passport.showNavigation({
  bottom?: "5px",
  right?: "5px",
  left?: "inherit",
  top?: "inherit",
}, {
  minimization?: {
    enabled?: boolean, // false
    toggler?: {
      enabled?: boolean, // false
      position?: Passport.navMinimizationTogglerPositions.(LEFT | RIGHT), // left
    }
  }
}); // Bottom right corner

Hide navigation panel

passport.hideNavigation();

Passport UI mode

Open UI (Use one of Credenza.pages.PROFILE, Credenza.pages.PASSPORT_ID)

await passport.openUI() // defaults to Credenza.pages.PROFILE

Close UI

passport.close()

Open Passport alert

passport.toastAlert(
  message,
  type?: 'success' | 'warning' | 'failure' | 'info', // defaults to info
  opts?:{
    duration?: number // if -1 - then there is no timer and it stays untill dismissed,
    centered?: {
      enabled?: boolean,
      position?: 'top' | 'bottom' // can be used only for centered block
    }
  }
)

Perform NFT or Membership payment

await passport.openUI(Passport.pages.PAYMENT, {
  title: string,
  subtitle: string,
  payments?: {
    credenzaStoredValue?: {
        disabled?: boolean //default - false
    },
    stripe?: {
        disabled?: boolean // default - false
    }
  },
  tokens: [{
    address: string, // contract address
    tokenId: string,
    amount?: number  // amount of tokens
  }],
  memberships: [
    {
      address: string, // contract address
      typeId?: string // If typeId === "0", API will treat it as a simple memberships purchase. If typeId > "0", ex. "1", "2", API will look for club memberships purchase.
    }
  ]
  email?: {
    templateId?: string // For custom email template usage
  }
})

Destroy passport

passport.destroy()

Events (Most likely for Navigation and UI modes)

Triggers when user logs in

passport.onLogin(({provider, opts}) => {
  console.log('User is logged in with passport', {provider, opts})
})

Triggers when user updates profile (extended registration uses this event too)

passport.onUpdateProfile((user) => {
  console.log('User profile updated: ', user)
})

Triggers when users logs out

passport.onLogout(async () => {
  console.log('User is logged out with passport')
})

Triggers when a payment is completed

passport.onPayment(async ({type: string, data: any}) => {
  console.log('Payment', {type, data})
})

Triggers when user change metamask account

passport.onMetamaskAccountChange(async (account) => {
  console.log(`User changed metamask account to: ${account}`)
})

Triggers when user account is confirmed

passport.onAccountConfirmed(({ phone?: string; email?: string }) => {
  console.log('Account confirmed', {phone, email})
})

Triggers when user sent some tokens

passport.onSendTokens(async ({ tx }) => {
  console.log('TX hash:', tx.hash)
  const receipt = await tx.wait()
  // or
  const receipt = await passport.provider.waitForTransaction(tx.hash)
  console.log(receipt)
})

Triggers when user sent nft(s)

passport.onSendNft(async ({ tx }) => {
  console.log('TX hash:', tx.hash)
  const receipt = await tx.wait()
  // or
  const receipt = await passport.provider.waitForTransaction(tx.hash)
  console.log(receipt)
})

Triggers when airdrop is requested

passport.onRequestAirdrop(async (data) => {
  console.log(data)
})

Triggers when loyalty points are requested

passport.onRequestLoyaltyPoints(async (data) => {
  console.log(data)
})

Triggers when passport UI is closed

passport.onUIClose(async (data:{page:string; pageOpts:object}) => {
  console.log(data)
})

Triggers when passport error occurs

passport.onError(({provider, error}) => {
  console.log('Passport error', {provider, error})
})

Supported query params

Prepopulates email address on login / signup form.

?credenza_user_email=test%40test.com
// ?credenza_user_email=encodeURIComponent(test@test.com)

SSR

Passport is not build for the Server Side Rendering, but you still can make it work with the SSR app. Make sure you disable SSR for passport specific component or you can dynamically import passport after it's mounted e.g.

// svelte
onMount(() => {
  const {Passport} = (await import('@credenza-web3/passport'))
})