@dogeos/dogeos-sdk 4.0.0-beta.9 → 4.0.1

package/dist/index.d.ts

@@ -17,8 +17,63 @@ import { WalletInfo } from '@tomo-inc/wallet-adaptor-base';
 import { WalletProvider } from '@tomo-inc/inject-providers';
 import { WalletProvider as WalletProvider_2 } from '@tomo-inc/wallet-adaptor-base';
 
+declare type AuthAssurance = "baseline" | "strong";
+
+declare type AuthClientState = {
+    kind: "anonymous";
+} | {
+    kind: "authenticating";
+    flowId: FlowId;
+} | {
+    kind: "authenticated";
+    session: AuthSessionProjection;
+} | {
+    kind: "error";
+    error: DogeOSAuthError;
+};
+
+declare type AuthErrorCode = "invalid_client" | "unsupported_protocol" | "invalid_delivery" | "provider_cancelled" | "provider_rejected" | "invalid_state" | "flow_interrupted" | "flow_expired" | "email_address_invalid" | "email_code_invalid" | "email_challenge_expired" | "email_challenge_exhausted" | "email_delivery_unavailable" | "attestation_enrollment_required" | "attestation_challenge_expired" | "attestation_rejected" | "handoff_replayed" | "proof_required" | "assurance_required" | "session_revoked" | "reauthentication_required" | "cleanup_required" | "wallet_mfa_dependency_unavailable" | "rate_limited" | "temporarily_unavailable";
+
+declare type AuthErrorResponse = {
+    code: AuthErrorCode;
+    message: string;
+    correlationId: string;
+};
+
+declare type AuthInteraction = {
+    kind: "relay_hosted";
+    mode: "popup" | "redirect";
+} | {
+    kind: "client_owned";
+} | {
+    kind: "embedded_wallet";
+    walletOrigin: string;
+    iframeChallenge: string;
+};
+
+declare type AuthMutationContext = {
+    readonly idempotencyKey: string;
+};
+
+declare type AuthProvider = "google" | "apple" | "x" | "email";
+
+declare type AuthSessionProjection = {
+    familyId: SessionFamilyId;
+    subjectId: string;
+    accountId: string;
+    tenantId: string;
+    clientId: ClientId;
+    sessionEpoch: number;
+    assurance: AuthAssurance;
+    expiresAt: string;
+};
+
 export declare type BasicLoginType = "email" | "externalWallets";
 
+declare type BrandedId<Name extends string> = string & {
+    readonly [idBrand]: Name;
+};
+
 export declare type Chain = {
     id: number;
     name: string;
@@ -67,6 +122,8 @@ export declare enum ChainTypeEnum {
     SUI = "sui"
 }
 
+declare type ClientId = BrandedId<"ClientId">;
+
 export declare interface ConnectData {
     address: string;
     chainId: string;
@@ -83,6 +140,54 @@ export declare interface ConnectVariables {
     chainId?: string;
 }
 
+declare type CreateEmailAuthFlowResponse = {
+    flowId: FlowId;
+    operationCredential: string;
+    expiresAt: string;
+    interaction: EmailFlowInteraction;
+};
+
+declare type CreateEmailFlowOptions = {
+    interaction?: AuthInteraction;
+    mutation?: AuthMutationContext;
+};
+
+declare class DogeOSAuthError extends Error {
+    readonly code: AuthErrorCode;
+    readonly correlationId: string | null;
+    constructor(args: {
+        code: AuthErrorCode;
+        message: string;
+        correlationId?: string | null;
+    });
+}
+
+export declare type DogeOSAuthFacade = {
+    state: AuthClientState;
+    readonly email: DogeOSEmailAuthClient;
+    login(options: LoginOptions): Promise<AuthSessionProjection>;
+    getSession(): Promise<AuthSessionProjection | null>;
+    refresh(): Promise<AuthSessionProjection>;
+    reauthenticate(requirement: ReauthenticationRequirement): Promise<AuthSessionProjection>;
+    logout(): Promise<void>;
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+};
+
+declare interface DogeOSEmailAuthClient {
+    create(options?: CreateEmailFlowOptions): Promise<EmailAuthFlowHandle>;
+    start(options: EmailStartOptions): Promise<EmailStartOutcome>;
+    resend(options: EmailStartOptions): Promise<EmailStartOutcome>;
+    verify(options: EmailVerifyOptions): Promise<EmailVerificationOutcome>;
+    status(options: EmailStatusOptions): Promise<EmailFlowStatus>;
+    cancel(options: EmailCancelOptions): Promise<EmailCancelReceipt>;
+    complete(options: EmailCompleteOptions): Promise<EmailAuthSessionProjection>;
+    /**
+     * Reconciles a safe session-scoped capsule with Relay. This performs only a
+     * status read; it never starts or resends email.
+     */
+    resume(): Promise<EmailFlowStatus | null>;
+}
+
 export declare type DogeOSEmbeddedWalletConfig = Omit<DogeOSEmbeddedWalletInitConfig, "stage"> & {
     stage?: EmbeddedWalletStage;
 };
@@ -91,6 +196,117 @@ export declare type DogeOSEmbeddedWalletInitConfig = Omit<EmbeddedWalletConfig,
     stage: EmbeddedWalletStage;
 };
 
+/**
+ * An email flow plus its original delivery verifier. Keep this object in
+ * volatile memory only. If its runtime is interrupted, discard it and surface
+ * `flow_interrupted`; do not persist or reconstruct its secrets.
+ */
+declare type EmailAuthFlowHandle = CreateEmailAuthFlowResponse & {
+    verifier: string;
+};
+
+/** Email possession establishes only baseline product authentication. */
+declare type EmailAuthSessionProjection = AuthSessionProjection & {
+    assurance: "baseline";
+};
+
+declare type EmailCancelOptions = EmailFlowAuthorization & {
+    mutation?: AuthMutationContext;
+};
+
+declare type EmailCancelReceipt = {
+    flowId: FlowId;
+    status: "cancelled";
+    cancelledAt: string;
+};
+
+declare type EmailChallengeId = BrandedId<"EmailChallengeId">;
+
+declare type EmailChallengeStatus = {
+    challengeId: EmailChallengeId;
+    status: "dispatching" | "code_sent" | "verifying" | "verified" | "exhausted" | "expired" | "cancelled";
+    expiresAt?: string;
+    resendAfter?: string;
+    failuresRemaining?: number;
+    sendsRemaining?: number;
+};
+
+declare type EmailCompleteOptions = EmailFlowAuthorization & {
+    verifier: string;
+    mutation?: AuthMutationContext;
+};
+
+declare type EmailFlowAuthorization = {
+    flowId: FlowId;
+    operationCredential: string;
+};
+
+declare type EmailFlowInteraction = {
+    kind: "relay_hosted";
+    state: "bootstrap_required";
+    bootstrap: {
+        action: string;
+        credential: string;
+    };
+} | {
+    kind: "client_owned";
+    state: "ready";
+} | {
+    kind: "embedded_wallet";
+    state: "ready";
+};
+
+declare type EmailFlowStatus = {
+    flowId: FlowId;
+    phase: "pending" | "processing" | "completed";
+    resumable: true;
+    challenge?: EmailChallengeStatus;
+} | {
+    flowId: FlowId;
+    phase: "failed" | "expired" | "cancelled";
+    resumable: false;
+    error: AuthErrorResponse;
+    challenge?: EmailChallengeStatus;
+};
+
+declare type EmailStartOptions = EmailFlowAuthorization & {
+    email: string;
+    mutation?: AuthMutationContext;
+};
+
+declare type EmailStartOutcome = {
+    challengeId: EmailChallengeId;
+    status: "dispatching";
+    destinationHint: string;
+    statusUrl: string;
+} | {
+    challengeId: EmailChallengeId;
+    status: "code_sent";
+    destinationHint: string;
+    expiresAt: string;
+    resendAfter: string;
+};
+
+declare type EmailStatusOptions = EmailFlowAuthorization;
+
+declare type EmailVerificationOutcome = {
+    flowId: FlowId;
+    status: "completed";
+} | {
+    flowId: FlowId;
+    status: "processing";
+};
+
+declare type EmailVerifyOptions = EmailFlowAuthorization & {
+    challengeId: EmailChallengeId;
+    /**
+     * Opaque, provider-delivered verifier segment. The SDK must not infer a
+     * numeric format, length, or leading-zero semantics from it.
+     */
+    code: string;
+    mutation?: AuthMutationContext;
+};
+
 declare interface EmbeddedWalletConnectedInfo {
     evmProvider?: ProviderConnectionInfo;
     solanaProvider?: ProviderConnectionInfo;
@@ -110,6 +326,8 @@ declare interface EmbeddedWalletState {
 
 export declare type EvmChain = Chain_2;
 
+declare type FlowId = BrandedId<"FlowId">;
+
 /**
  * Get all available chains
  * Fetches chains from backend API and returns all supported chains in config format
@@ -130,6 +348,15 @@ export declare function getConnectors(): Promise<WalletConfig[]>;
 
 export declare type GetConnectorsReturnType = Promise<WalletConfig[]>;
 
+declare const idBrand: unique symbol;
+
+declare type LoginOptions = {
+    provider: "email";
+    email: string;
+} | {
+    provider: Exclude<AuthProvider, "email">;
+};
+
 export declare enum ModalView {
     Loading = "LOADING",
     WalletList = "WALLET_LIST",
@@ -167,10 +394,25 @@ export declare interface ProviderInfo {
     walletId?: string;
 }
 
+declare type ReauthenticationRequestId = BrandedId<"ReauthenticationRequestId">;
+
+declare type ReauthenticationRequirement = {
+    requestId: ReauthenticationRequestId;
+    audience: string;
+    maxSessionAgeSeconds: number;
+    expiresAt: string;
+};
+
+declare type SessionFamilyId = BrandedId<"SessionFamilyId">;
+
 export { SignInParams }
 
 export declare interface SocialLoginProvider {
     type: SocialLoginType;
+    /**
+     * @deprecated Provider OAuth client IDs are authority-owned and ignored by
+     * the SDK. Consumers only select which provider controls to display.
+     */
     clientId?: string;
     [key: string]: unknown;
 }
@@ -219,6 +461,8 @@ export declare const useConnectors: () => {
     currentProvider: WalletProvider_2 | null;
 };
 
+export declare function useDogeOSAuth(): DogeOSAuthFacade;
+
 /**
  * Internal hook to access embedded wallet state.
  * NOT part of the public API — use `useWalletConnect()` for readiness.
@@ -267,6 +511,16 @@ declare interface WalletConnectEmbedProps {
 }
 
 export declare interface WalletConnectKitConfig {
+    /**
+     * Gateway origin for proof-bound product requests such as the wallet
+     * continuation admission call (custody migration gate). Optional; when
+     * omitted the continuation check is skipped and login behaves as before.
+     * @example
+     * ```tsx
+     * const config: WalletConnectKitConfig = { gatewayBaseUrl: "https://wallet.mydoge.com" };
+     * ```
+     */
+    gatewayBaseUrl?: string;
     /**
      * Connector configuration
      * Must be obtained through getConnectors() method, cannot be passed directly