@keyban/sdk-base
Version:
Keyban Javascript SDK provides core functionalities for the MPC wallet solution, supporting web and Node.js apps with TypeScript, custom storage, and Ethereum blockchain integration.
278 lines (274 loc) • 9.83 kB
TypeScript
import { Application, AuthUser, Hex, DppProduct, DppPassport, DppClaimResult, LoyaltyRewardTier, Network } from '@keyban/types';
/**
* @module API
* Cross-window iframe API contracts and client/server helpers.
*/
type KeybanApiStatus = "operational" | "down";
/**
* Application service.
*/
interface IApplicationService {
/** Returns the current application. */
getCurrent: () => Promise<Application>;
}
/**
* Arguments for sending a One-Time Password (OTP).
*
* @example
* // Email OTP
* const args: AuthSendOtpArgs = {
* type: "email-otp",
* emailInputName: "email",
* };
*
* @example
* // Phone/SMS OTP
* const args: AuthSendOtpArgs = {
* type: "phone-otp",
* phoneCallingCode: "+33",
* phoneInputName: "phone",
* };
*/
type AuthSendOtpArgs = {
type: "email-otp";
emailInputName: string;
} | {
type: "phone-otp";
phoneCallingCode: string;
phoneInputName: string;
};
/**
* Arguments for signing up a user using email and password.
*/
type AuthSignUpArgs = {
type: "email-password";
emailInputName: string;
passwordInputName: string;
passwordConfirmInputName?: string;
nameInputName?: string;
};
/**
* Arguments for signing in a user.
*/
type AuthSignInArgs = {
type: "email-password";
emailInputName: string;
passwordInputName: string;
} | {
type: "email-otp";
emailInputName: string;
otpInputName: string;
} | {
type: "phone-otp";
phoneCallingCode: string;
phoneInputName: string;
otpInputName: string;
} | {
type: "social-google";
};
type AuthUpdateUserArgs = {
name: string;
birthDate: string;
};
/**
* Authentication service.
*
* @see {@link IKeybanApi}
*/
interface IAuthService {
/** Checks whether the current user is authenticated. */
isAuthenticated: () => Promise<boolean>;
/** Retrieves the authenticated user profile, or null. */
getUser: () => Promise<AuthUser | null>;
/** Sends an OTP to email or phone. */
sendOtp: (args: AuthSendOtpArgs) => Promise<void>;
/** Registers a new user account. */
signUp: (args: AuthSignUpArgs) => Promise<AuthUser>;
/** Signs in a user using password or OTP. */
signIn: (args: AuthSignInArgs) => Promise<AuthUser>;
/** Signs out the current user. */
signOut: () => Promise<void>;
/** Updates the user profile. */
updateUser: (args: AuthUpdateUserArgs) => Promise<AuthUser>;
}
/**
* MPC signer for a given curve (ECDSA/EdDSA).
*/
interface ISignerService {
/** Performs a Distributed Key Generation ceremony, returning a client share. */
dkg: () => Promise<string>;
/** Signs a pre-hashed message with the server share and provided client share. */
sign: (clientShare: string, message: string) => Promise<Hex>;
/** Derives the public key associated with the provided client share. */
publicKey: (clientShare: string) => Promise<Hex>;
}
/**
* Account service.
*/
interface IAccountService {
/** Returns the on-chain address of the user account. */
getAddress: () => Promise<string>;
getId: () => Promise<string>;
}
/**
* Storage for persisting and retrieving the MPC client share on the integrator side.
*/
interface IClientShareStorageService {
/** Retrieves a stored client share by key. */
get: (key: string) => Promise<string | null>;
/** Stores a client share under the given key. */
set: (key: string, clientShare: string) => Promise<void>;
}
/**
* Digital Product Passport (DPP) operations.
*
* Provides methods to retrieve product information and claim DPPs on the blockchain.
* All claim operations return a transaction hash that can be used to track the
* on-chain transaction status.
* @example
* ```typescript
* // Retrieve a product sheet
* const product = await dppService.getProduct("prod_123");
* console.log(product.name, product.description);
*
* // Claim a DPP with explicit product sheet and DPP IDs
* const { transactionHash } = await dppService.claim("prod_123", "dpp_456");
* console.log("Transaction:", transactionHash);
*
* // Claim a DPP using a magic token (single-use claim link)
* const result = await dppService.magicClaim("prod_123", "magic_xyz");
* ```
*/
interface IDppService {
/**
* Retrieves a single product sheet by ID.
*
* Returns comprehensive product information including name, description, images,
* brand, country of origin, identifiers (GTIN, SKU), certification paths,
* network status, and timestamps.
* @param productId - Unique identifier of the product to retrieve
* @returns Promise resolving to the product with complete product data
* @throws {SdkError} If the product is not found or the user lacks permission
* @example
* ```typescript
* const sheet = await dppService.getProduct("prod_abc123");
* console.log("Product:", sheet.name, "by", sheet.brand);
* console.log("Status:", sheet.status); // "ACTIVE", "ARCHIVED", "DRAFT", "UNLISTED"
* ```
*/
getProduct: (productId: string) => Promise<DppProduct>;
/**
* Retrieves a single passport by ID.
*
* @param passportId - Unique identifier of the passport to retrieve
* @returns Promise resolving to the passport with complete passport data
* @throws {SdkError} If the passport is not found or the user lacks permission
* @example
* ```typescript
* const passport = await dppService.getPassport("prod_abc123");
* console.log("Passport:", passport);
* ```
*/
getPassport: (passportId: string) => Promise<DppPassport>;
/**
* Claims a Digital Product Passport (DPP) on the blockchain.
*
* Associates a specific DPP instance with the authenticated user's account by
* creating an on-chain claim transaction. The user must be authenticated and
* authorized to claim the specified DPP.
* @param productId - Product sheet identifier defining the product type
* @param passportId - Specific DPP instance identifier to claim (unique serial number)
* @returns Promise resolving to the claim result with transaction hash
* @throws {SdkError} If authentication fails, DPP is already claimed, or transaction fails
* @example
* ```typescript
* const result = await dppService.claim("prod_shirt_001", "dpp_serial_12345");
* console.log("DPP claimed! Transaction:", result);
* // transactionHash format: "0x..." (Ethereum) or similar depending on network
* ```
*/
claim: (productId: string, passportId: string) => Promise<DppClaimResult>;
/**
* Claims a Digital Product Passport using a single-use magic token.
*
* Simplified claim flow using a pre-authorized token (typically from a QR code
* or claim link). The magic token embeds the DPP authorization, allowing claim
* without explicitly specifying the DPP ID.
* @param productId - Product sheet identifier for the product being claimed
* @param magicToken - Single-use authorization token for claiming a specific DPP
* @returns Promise resolving to the claim result with transaction hash
* @throws {SdkError} If the token is invalid, expired, already used, or transaction fails
* @example
* ```typescript
* // Magic token typically obtained from scanning QR code or clicking claim link
* const magicToken = "*****";
* const result = await dppService.magicClaim("prod_shirt_001", magicToken);
* console.log("DPP claimed via magic link!", result);
* ```
*/
magicClaim: (productId: string, magicToken: string) => Promise<DppClaimResult>;
}
/**
* Loyalty operations for wallet passes and tier retrieval.
*/
interface ILoyaltyService {
/** Returns the current loyalty optimistic balance. */
getOptimisticBalance: () => Promise<string>;
/** Returns the current loyalty reward tier, or null if none. */
getRewardTier: () => Promise<LoyaltyRewardTier | null>;
/** Returns a Google Wallet URL to add the pass. */
addToGoogleWallet: () => Promise<string>;
/** Adds an Apple Wallet pass. */
addToAppleWallet: () => Promise<void>;
}
/**
* Aggregated API surface exposed through the iframe transport.
*/
interface IKeybanApi {
application: IApplicationService;
auth: IAuthService;
ecdsa: ISignerService;
eddsa: ISignerService;
account: IAccountService;
clientShareStorage: IClientShareStorageService;
dpp: IDppService;
loyalty: ILoyaltyService;
}
/**
* @private
*/
declare abstract class ApiServer implements IKeybanApi {
#private;
abstract application: IApplicationService;
abstract auth: IAuthService;
abstract ecdsa: ISignerService;
abstract eddsa: ISignerService;
abstract account: IAccountService;
abstract loyalty: ILoyaltyService;
abstract clientShareStorage: IClientShareStorageService;
abstract dpp: IDppService;
constructor();
abstract checkEventOrigin(eventOrigin: string): Promise<boolean>;
static openPopup(url: URL | string): Promise<void>;
}
type ApiClientOptions = {
apiUrl: URL | string;
appId: string;
network: Network;
};
/**
* @private
*/
declare class ApiClient {
#private;
/**
* Returns a shared instance per unique iframe URL.
*
* @param options - API client options.
* @returns ApiClient instance bound to the provided options.
*/
static getInstance(options: ApiClientOptions): ApiClient;
api: IKeybanApi;
private constructor();
}
export { ApiClient, ApiServer, type AuthSendOtpArgs, type AuthSignInArgs, type AuthSignUpArgs, type AuthUpdateUserArgs, type IAccountService, type IApplicationService, type IAuthService, type IClientShareStorageService, type IDppService, type IKeybanApi, type ILoyaltyService, type ISignerService, type KeybanApiStatus };