packages/pass/lib/bridge/INTEGRATION.md

   1 # Pass Bridge
   2
   3 ### Usage
   4
   5 #### Factory
   6
   7 Import the factory function and create a `PassBridge` instance with the necessary options.
   8
   9 ```ts
  10 import { createPassBridge } from '@proton/pass/lib/bridge';
  11
  12 const PassBridge = createPassBridge({ api, user, addresses, authStore });
  13 ```
  14
  15 #### React
  16
  17 In react, you can use the `PassBridgeProvider` component which will take care of creating the bridge and use the `usePassBridge` hook in the subtree.
  18
  19 ```tsx
  20 import { PassBridgeProvider, usePassBridge } from '@proton/pass/lib/bridge/PassBridgeProvider';
  21 ```
  22
  23 ⚠️ Make sure the underlying models are available when creating the context. `PassBridge` requires the user and addresses to be fully loaded to instantiate properly.
  24
  25 ### Aliases
  26
  27 #### Integration example
  28
  29 ```ts
  30 // Get all the aliases for the default user vault. If no vaults
  31 // are available, a default one will be created.
  32 const defaultVault = await PassBridge.vault.getDefault();
  33 const aliasItems = await PassBridge.alias.getAllByShareId(defaultVault.shareId);
  34
  35 // Relevant information for alias items :
  36 const { item, aliasDetails } = aliasItems[0]
  37 const aliasEmail = aliasDetails.aliasEmail
  38 const aliasMailboxes = aliasDetails.mailboxes
  39 const { name, note } = item.data.metadata
  40 // note is obfuscated, if you need to read it :
  41 import { deobfuscate } from '@proton/pass/utils/obfuscate/xor'
  42 const clearNote = deobfuscate(note)
  43
  44 // Before creating a new alias, you need to request the current
  45 // alias options - these options have a validity window of 10 minutes
  46 // after which you will have to re-query the alias options. These options
  47 // will give you the available suffixes and mailboxes
  48 const aliasOptions = await PassBridge.alias.getAliasOptions(defaultVault.shareId);
  49
  50 // Creating an alias : let the user select the desired prefix, suffix and target mailbox.
  51 // You can validate the final aliasEmail before submitting (prefix + suffix).
  52 const prefix = 'some-user-input';
  53 const mailbox = aliasOptions.mailboxes[0];
  54 const { suffix, signedSuffix } = aliasOptions.suffixes[1];
  55 const aliasEmail = `${prefix}${signedSuffix}`;
  56
  57 const alias = await PassBridge.alias.create({
  58     shareId: defaultVault.shareId,
  59     name: 'Alias for ProtonMail',
  60     note: 'Alias created from mail widget',
  61     alias: {
  62         mailbox,
  63         signedSuffix,
  64         prefix,
  65         aliasEmail,
  66     },
  67 });
  68 ```