@credenza-web3/passport v5.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?: {
      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.`
      }
    },
    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>

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

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)

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

Close UI

passport.close()

Perform NFT or Membership payment

passport.openUI(Passport.pages.PAYMENT, {
  title: string,
  subtitle: string,
  payments?: {
    credenzaStoredValue?: {
        disabled?: boolean //default - false
    },
    stripe?: {
        disabled?: boolean // default - false
    }
  },
    // This will help credenza to get a price and figure out a token to be transferred
  token?: {
    address: string, // contract address
    tokenId?: string, // token id if exists
    amount?: number  // amount of tokens if exists. For ERC721 either ignore it, or set 1.
    typeId?: number // if buying membership and typeId exists. Should be either tokenId or typeId
  },
  email?: {
    templateId?: string // For custom email template usage
  }
})

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 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)