@spare-technologies/spare-link 0.1.0-beta.0 → 1.0.0

package/src/public/recovery-result.ts

@@ -2,40 +2,35 @@ import type { PaymentResult } from './payment-result';
 
 /**
  * Why {@link SpareLink.resumeIfNeeded} did not recover a terminal session.
- * Mirrors Flutter's `NoRecoveryReason`.
- */
-export type NoRecoveryReason = 'noPendingSession' | 'flowAlreadyActive' | 'persistenceUnavailable';
-
-/**
- * Outcome of {@link SpareLink.resumeIfNeeded}.
  *
- * Discriminated union aligned with Flutter's sealed `RecoveryResult`.
+ * `outcomeUnknown` is the one that carries weight: a payment was pending and no
+ * return arrived, so **it may have completed**. The SDK holds no credentials and
+ * has nothing to ask with — the reference is handed back for your backend to
+ * resolve.
  */
-export type RecoveryResult = NoRecoveryNeeded | SessionRecovered | RecoveryAwaitingUser;
+export type NoRecoveryReason =
+  | 'noPendingSession'
+  | 'flowAlreadyActive'
+  | 'persistenceUnavailable'
+  | 'outcomeUnknown';
 
-/** No pending session was recovered. */
+/** Outcome of {@link SpareLink.resumeIfNeeded}. */
+export type RecoveryResult = NoRecoveryNeeded | SessionRecovered;
+
+/** No pending payment was resolved to a terminal outcome. */
 export interface NoRecoveryNeeded {
   readonly kind: 'none';
   readonly reason: NoRecoveryReason;
+  /** The pending payment's reference, when `reason` is `outcomeUnknown`. */
+  readonly reference?: string;
 }
 
-/** A pending session was recovered to a terminal {@link PaymentResult}. */
+/** A pending payment was resolved to a terminal {@link PaymentResult}. */
 export interface SessionRecovered {
   readonly kind: 'recovered';
   readonly result: PaymentResult;
 }
 
-/**
- * A pending session is non-terminal and the SDK opened its recovery UI —
- * the integrator should treat this as in-progress, not "nothing happened".
- * The terminal outcome arrives later via `SpareLink.events` /
- * `spareLink.emitTerminal`, not as a second `resumeIfNeeded` resolution.
- */
-export interface RecoveryAwaitingUser {
-  readonly kind: 'awaitingUser';
-  readonly linkToken: string;
-}
-
 export function isSessionRecovered(r: RecoveryResult): r is SessionRecovered {
   return r.kind === 'recovered';
 }
@@ -43,7 +38,3 @@ export function isSessionRecovered(r: RecoveryResult): r is SessionRecovered {
 export function isNoRecoveryNeeded(r: RecoveryResult): r is NoRecoveryNeeded {
   return r.kind === 'none';
 }
-
-export function isRecoveryAwaitingUser(r: RecoveryResult): r is RecoveryAwaitingUser {
-  return r.kind === 'awaitingUser';
-}

package/src/public/spare-link-config.ts

@@ -1,24 +1,48 @@
+import { Platform } from 'react-native';
+
+/**
+ * Deployment environment for the Spare Link API, which is also where the hosted
+ * payment page is served from.
+ */
+export type PaymentEnvironment = 'local' | 'dev' | 'sandbox' | 'production';
+
+/** Default port an Encore app serves on. */
+const LOCAL_PORT = 4000;
+
 /**
- * Deployment environment for the Spare Link API.
+ * A Spare API running on the developer's own machine.
+ *
+ * The host differs by platform because an emulator's `localhost` is the emulator,
+ * not the machine hosting it. A **physical device** reaches neither, so pass
+ * `baseUrl` with your machine's address on the local network instead.
  *
- * Each value maps to a default base URL
- * the SDK will hit unless `baseUrl` is overridden in {@link SpareLinkConfig}.
+ * Serves over plain HTTP, which both platforms block by default. See the
+ * integration notes for the debug-only exceptions that allow it.
  */
-export type PaymentEnvironment = 'sandbox' | 'production';
+function localBaseUrl(): string {
+  return Platform.OS === 'android'
+    ? `http://10.0.2.2:${LOCAL_PORT}`
+    : `http://localhost:${LOCAL_PORT}`;
+}
 
-const DEFAULT_BASE_URLS: Record<PaymentEnvironment, string> = {
+/**
+ * `dev` is Spare's own integration environment, not one an integrator would ship
+ * against. Unlike the others its host names a single tenant, so it serves UAE alone.
+ */
+const DEFAULT_BASE_URLS: Readonly<Record<Exclude<PaymentEnvironment, 'local'>, string>> = {
+  dev: 'https://api-dev-uae.tryspare.ae',
   sandbox: 'https://api.sandbox.tryspare.ae',
   production: 'https://api.tryspare.ae',
 };
 
 export function defaultBaseUrlFor(env: PaymentEnvironment): string {
-  return DEFAULT_BASE_URLS[env];
+  return env === 'local' ? localBaseUrl() : DEFAULT_BASE_URLS[env];
 }
 
 /** Spare API tenant — one country per tenant. */
 export type SpareApiTenant = 'ksa' | 'uae' | 'bah';
 
-const TENANT_COUNTRY_CODES: Record<SpareApiTenant, string> = {
+const TENANT_COUNTRY_CODES: Readonly<Record<SpareApiTenant, string>> = {
   ksa: 'KSA',
   uae: 'UAE',
   bah: 'BAH',
@@ -28,31 +52,19 @@ export function tenantCountryCode(t: SpareApiTenant): string {
   return TENANT_COUNTRY_CODES[t];
 }
 
-/** Configuration to start a Spare Link payment flow. */
+/** Configuration for a Spare Link instance. */
 export interface SpareLinkConfig {
-  /** One-time link token minted by the merchant backend via POST /link/token/payment. */
-  linkToken: string;
-
-  /** Target environment (sandbox vs production). */
+  /** Target environment. Selects the host the hosted page is loaded from. */
   environment: PaymentEnvironment;
 
-  /** Tenant (country). */
-  tenant: SpareApiTenant;
-
-  /**
-   * Override the base URL. Set only for local dev (e.g. `http://localhost:4000`)
-   * — production should rely on the environment-derived default.
-   */
-  baseUrl?: string;
-
   /**
-   * Inject a custom fetch implementation for advanced cases (cert pinning,
-   * request logging). Defaults to `globalThis.fetch`.
+   * Tenant (country). The hosted flow currently serves UAE only; the value is
+   * kept for that selection and for the tenants that follow.
    */
-  fetch?: typeof fetch;
+  tenant: SpareApiTenant;
 
-  /** Per-request timeout in milliseconds. Defaults to 15000. */
-  requestTimeoutMs?: number;
+  /** Override the host. Set for a physical device pointed at a local API. */
+  baseUrl?: string;
 }
 
 /** Resolved base URL: explicit `baseUrl` if provided, else the environment default. */
@@ -61,27 +73,28 @@ export function resolvedBaseUrl(config: SpareLinkConfig): string {
 }
 
 /**
- * Recovery config — like {@link SpareLinkConfig} but without `linkToken`
- * (read from the persisted record).
+ * The tenants the hosted flow can actually serve.
+ *
+ * `tenant` accepts the others because the API surface outlives this list, but
+ * accepting one the page cannot serve would put a payer in front of the wrong
+ * country's flow rather than telling the integrator at construction time.
  */
-export interface SpareLinkResumeConfig {
-  environment: PaymentEnvironment;
-  tenant: SpareApiTenant;
-  baseUrl?: string;
-  fetch?: typeof fetch;
-  requestTimeoutMs?: number;
-}
+const SUPPORTED_TENANTS: readonly SpareApiTenant[] = ['uae'];
 
-export function resolvedResumeBaseUrl(config: SpareLinkResumeConfig): string {
-  return config.baseUrl ?? defaultBaseUrlFor(config.environment);
-}
-
-/** Throws if a SpareLinkConfig is structurally invalid. */
+/**
+ * Throws if a config cannot be honoured.
+ *
+ * Called from {@link SpareLink}'s constructor, so a bad value fails where it was
+ * written rather than reaching the webview as a URL nobody meant.
+ */
 export function assertValidConfig(config: SpareLinkConfig): void {
-  if (!config.linkToken) {
-    throw new Error('SpareLinkConfig: linkToken must not be empty');
-  }
   if (config.baseUrl && !/^https?:\/\//.test(config.baseUrl)) {
     throw new Error('SpareLinkConfig: baseUrl must start with http:// or https://');
   }
+  if (!SUPPORTED_TENANTS.includes(config.tenant)) {
+    throw new Error(
+      `SpareLinkConfig: the hosted flow does not serve tenant '${config.tenant}' yet ` +
+        `(supported: ${SUPPORTED_TENANTS.join(', ')})`,
+    );
+  }
 }

package/src/public/spare-link-event.ts

@@ -3,20 +3,21 @@ import type { PaymentResult } from './payment-result';
 /**
  * Lifecycle events emitted on {@link SpareLink.events}.
  *
- * This is a discriminated union (TypeScript's equivalent to Dart sealed classes).
- * Use a switch on the `type` field for exhaustive handling:
+ * Analytics only — never required to drive the flow. This is a discriminated
+ * union (TypeScript's equivalent to Dart sealed classes); switch on `type` for
+ * exhaustive handling:
  *
  * ```ts
  * spareLink.events.subscribe((event) => {
  *   switch (event.type) {
  *     case 'initialized':
- *       console.log('Started flow for', event.linkToken);
+ *       console.log('Started flow for', event.reference);
  *       break;
- *     case 'sessionLoaded':
- *       console.log('Session loaded', event.linkSessionId);
+ *     case 'pageReady':
+ *       console.log('Payer can act on the page');
  *       break;
  *     case 'succeeded':
- *       console.log('Payment succeeded', event.result.exchangeCode);
+ *       console.log('Reported success for', event.result.reference);
  *       break;
  *     // ...
  *   }
@@ -25,8 +26,7 @@ import type { PaymentResult } from './payment-result';
  */
 export type SpareLinkEvent =
   | SpareLinkInitialized
-  | SpareLinkSessionLoaded
-  | SpareLinkConsentStarted
+  | SpareLinkPageReady
   | SpareLinkRedirectToBank
   | SpareLinkBankCallbackReceived
   | SpareLinkSucceeded
@@ -37,36 +37,33 @@ export type SpareLinkEvent =
 /** The SDK has started a payment flow. */
 export interface SpareLinkInitialized {
   readonly type: 'initialized';
-  readonly linkToken: string;
+  readonly reference: string;
 }
 
-/** The payment session was loaded from the server. */
-export interface SpareLinkSessionLoaded {
-  readonly type: 'sessionLoaded';
-  readonly linkToken: string;
-  /** Server-assigned link session ID when available from the API. */
-  readonly linkSessionId?: string;
-}
-
-/** The user confirmed consent and a consent request was submitted. */
-export interface SpareLinkConsentStarted {
-  readonly type: 'consentStarted';
-  readonly linkToken: string;
+/**
+ * The hosted page is interactive and the payer has something to act on.
+ *
+ * The steps after this — choosing a bank, the payee check, reading the consent —
+ * happen inside the page, which does not report them.
+ */
+export interface SpareLinkPageReady {
+  readonly type: 'pageReady';
+  readonly reference: string;
 }
 
-/** The user is being redirected to their bank's authorization page. */
+/** The payer is being handed to their bank, outside the WebView. */
 export interface SpareLinkRedirectToBank {
   readonly type: 'redirectToBank';
-  readonly linkToken: string;
+  readonly reference: string;
 }
 
 /** The bank has redirected back with a callback URI. */
 export interface SpareLinkBankCallbackReceived {
   readonly type: 'bankCallbackReceived';
-  readonly linkToken: string;
+  readonly reference: string;
 }
 
-/** The payment completed successfully and the flow is about to resolve. */
+/** The return reported a completed payment and the flow is about to resolve. */
 export interface SpareLinkSucceeded {
   readonly type: 'succeeded';
   readonly result: PaymentResult;
@@ -78,13 +75,13 @@ export interface SpareLinkFailed {
   readonly result: PaymentResult;
 }
 
-/** The user cancelled the payment and the flow is about to resolve. */
+/** The payer cancelled the payment and the flow is about to resolve. */
 export interface SpareLinkCancelled {
   readonly type: 'cancelled';
   readonly result: PaymentResult;
 }
 
-/** The flow was abandoned without an explicit user action. */
+/** The payer left before the flow resolved either way. */
 export interface SpareLinkAbandoned {
   readonly type: 'abandoned';
   readonly result: PaymentResult;
@@ -93,8 +90,7 @@ export interface SpareLinkAbandoned {
 /** All possible event type strings for type narrowing. */
 export const SPARE_LINK_EVENT_TYPES = [
   'initialized',
-  'sessionLoaded',
-  'consentStarted',
+  'pageReady',
   'redirectToBank',
   'bankCallbackReceived',
   'succeeded',
@@ -114,22 +110,17 @@ export function isSpareLinkEvent(value: unknown): value is SpareLinkEvent {
 
 /** Factory functions for creating events (internal use). */
 export const SpareLinkEvents = {
-  initialized(linkToken: string): SpareLinkInitialized {
-    return { type: 'initialized', linkToken };
-  },
-  sessionLoaded(linkToken: string, linkSessionId?: string): SpareLinkSessionLoaded {
-    return linkSessionId
-      ? { type: 'sessionLoaded', linkToken, linkSessionId }
-      : { type: 'sessionLoaded', linkToken };
+  initialized(reference: string): SpareLinkInitialized {
+    return { type: 'initialized', reference };
   },
-  consentStarted(linkToken: string): SpareLinkConsentStarted {
-    return { type: 'consentStarted', linkToken };
+  pageReady(reference: string): SpareLinkPageReady {
+    return { type: 'pageReady', reference };
   },
-  redirectToBank(linkToken: string): SpareLinkRedirectToBank {
-    return { type: 'redirectToBank', linkToken };
+  redirectToBank(reference: string): SpareLinkRedirectToBank {
+    return { type: 'redirectToBank', reference };
   },
-  bankCallbackReceived(linkToken: string): SpareLinkBankCallbackReceived {
-    return { type: 'bankCallbackReceived', linkToken };
+  bankCallbackReceived(reference: string): SpareLinkBankCallbackReceived {
+    return { type: 'bankCallbackReceived', reference };
   },
   succeeded(result: PaymentResult): SpareLinkSucceeded {
     return { type: 'succeeded', result };

package/src/public/spare-link-host-api.ts

@@ -1,6 +1,5 @@
 import type { PaymentResult } from './payment-result';
 import type { RecoveryResult } from './recovery-result';
-import type { SpareLinkSession } from './spare-link-session';
 
 /**
  * Imperative API the {@link SpareLinkHost} mounts and wires to a
@@ -8,20 +7,8 @@ import type { SpareLinkSession } from './spare-link-session';
  *
  * @internal
  */
-export interface SpareLinkHostApi {
-  start(args: { linkToken: string }): Promise<SpareLinkSession>;
-  handleRedirect(uri: URL | string): Promise<boolean>;
-  resumeIfNeeded(): Promise<RecoveryResult>;
-  isFlowActive(): boolean;
-}
-
-/** @internal */
 export interface SpareLinkHostDelegate {
-  startFlow(args: {
-    linkToken: string;
-    resolve: (result: PaymentResult) => void;
-    onSessionLoaded?: (linkSessionId: string) => void;
-  }): void;
+  startFlow(args: { reference: string; resolve: (result: PaymentResult) => void }): void;
   handleRedirect(uri: URL | string): Promise<boolean>;
   resumeIfNeeded(): Promise<RecoveryResult>;
   isFlowActive(): boolean;

package/src/public/spare-link-instance.ts

@@ -1,10 +1,11 @@
 import type { PendingSessionStore } from '../core/services/pending-session-store';
 import { type EventEmitter, createEventEmitter } from '../internal/event-emitter';
 import { type PaymentResult, paymentAbandoned } from './payment-result';
-import { type NoRecoveryReason, type RecoveryResult, isSessionRecovered } from './recovery-result';
+import type { NoRecoveryReason, RecoveryResult } from './recovery-result';
 import {
   type PaymentEnvironment,
   type SpareApiTenant,
+  assertValidConfig,
   defaultBaseUrlFor,
 } from './spare-link-config';
 import { type SpareLinkEvent, SpareLinkEvents } from './spare-link-event';
@@ -15,14 +16,12 @@ export interface SpareLinkOptions {
   environment: PaymentEnvironment;
   tenant: SpareApiTenant;
   baseUrl?: string;
-  fetch?: typeof fetch;
-  requestTimeoutMs?: number;
   /** Store for crash-safe recovery. Defaults to none — wire e.g. `SecureStorePendingSessionStore`. */
   pendingSessionStore?: PendingSessionStore;
 }
 
 interface PendingStart {
-  linkToken: string;
+  reference: string;
   resolve: (session: SpareLinkSession) => void;
 }
 
@@ -36,8 +35,11 @@ interface PendingResume {
 }
 
 /**
- * Entry point for the Spare Link payment SDK — aligned with Flutter's
- * instance-based {@link SpareLink} API.
+ * Entry point for the Spare Link payment SDK.
+ *
+ * Your backend creates the payment request — with `channel: 'sdk_react_native'`
+ * and the return URLs your app is registered for — and gives the app the
+ * reference it returns. That reference is all this SDK needs.
  *
  * Mount {@link SpareLinkHost} once near your app root and pass this instance:
  *
@@ -51,13 +53,15 @@ interface PendingResume {
  *   <App />
  * </SpareLinkHost>
  * ```
+ *
+ * The SDK makes no API calls of its own and holds no credentials. Every result
+ * it reports comes from a deep link that is interceptable by design, so confirm
+ * with your backend via `GET /payment-requests/{reference}` before acting on one.
  */
 export class SpareLink {
   readonly environment: PaymentEnvironment;
   readonly tenant: SpareApiTenant;
   readonly baseUrl: string | undefined;
-  readonly fetch: typeof fetch | undefined;
-  readonly requestTimeoutMs: number | undefined;
   readonly pendingSessionStore: PendingSessionStore | undefined;
 
   private readonly _events = createEventEmitter<SpareLinkEvent>();
@@ -69,11 +73,17 @@ export class SpareLink {
   private readonly _pendingResumes: PendingResume[] = [];
 
   constructor(options: SpareLinkOptions) {
+    // Fails where the config was written rather than letting a host the page was
+    // never served from reach the webview as a URL nobody meant.
+    assertValidConfig({
+      environment: options.environment,
+      tenant: options.tenant,
+      ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+    });
+
     this.environment = options.environment;
     this.tenant = options.tenant;
     this.baseUrl = options.baseUrl;
-    this.fetch = options.fetch;
-    this.requestTimeoutMs = options.requestTimeoutMs;
     this.pendingSessionStore = options.pendingSessionStore;
   }
 
@@ -92,45 +102,34 @@ export class SpareLink {
   }
 
   /**
-   * Starts a new payment flow.
+   * Opens the hosted payment page for `reference` and resolves when the flow ends.
    *
-   * Returns a {@link SpareLinkSession} immediately; await `session.result`
-   * for the terminal outcome.
+   * Returns a {@link SpareLinkSession} immediately; await `session.result` for the
+   * terminal outcome. There is no session to load first: the page resolves the
+   * request itself, so the payer sees it without waiting on a round trip.
    */
-  async start(args: { linkToken: string }): Promise<SpareLinkSession> {
-    const { linkToken } = args;
-    if (!linkToken) {
-      const result = paymentAbandoned({
-        linkToken: '',
-        message: 'SpareLinkConfig: linkToken must not be empty',
-        resolvedAtMs: Date.now(),
-      });
-      this._emitTerminal(result);
-      return new SpareLinkSession({ linkToken: '', result: Promise.resolve(result) });
+  async start(args: { reference: string }): Promise<SpareLinkSession> {
+    const { reference } = args;
+    if (!reference) {
+      return this._resolveImmediately('', 'SpareLink.start: reference must not be empty');
     }
 
     if (this._disposed) {
-      const result = paymentAbandoned({
-        linkToken,
-        message: 'SpareLink has been disposed.',
-        resolvedAtMs: Date.now(),
-      });
-      this._emitTerminal(result);
-      return new SpareLinkSession({ linkToken, result: Promise.resolve(result) });
+      return this._resolveImmediately(reference, 'SpareLink has been disposed.');
     }
 
-    this._events.emit(SpareLinkEvents.initialized(linkToken));
+    this._events.emit(SpareLinkEvents.initialized(reference));
 
     if (!this._host) {
       return new Promise<SpareLinkSession>((resolve) => {
-        this._pendingStarts.push({ linkToken, resolve });
+        this._pendingStarts.push({ reference, resolve });
       });
     }
 
-    return this._hostStart(linkToken);
+    return this._hostStart(reference);
   }
 
-  /** Processes a deep-link URI received from the bank. */
+  /** Processes a deep-link URI the payer returned through. */
   async handleRedirect(uri: URL | string): Promise<boolean> {
     if (this._disposed) return false;
     if (!this._host) {
@@ -141,12 +140,16 @@ export class SpareLink {
     return this._host.handleRedirect(uri);
   }
 
-  /** Checks for a pending session saved during a previous flow and recovers it. */
+  /**
+   * Reports a payment that was left in progress by a previous app session.
+   *
+   * If the return deep link arrived before the app had a flow to give it to, the
+   * outcome is resolved from it. Otherwise the SDK cannot say how the payment
+   * ended — it holds no credentials, so it has nothing to ask with — and reports
+   * `outcomeUnknown` with the reference for your backend to resolve.
+   */
   async resumeIfNeeded(): Promise<RecoveryResult> {
-    if (this._disposed) {
-      return { kind: 'none', reason: 'persistenceUnavailable' };
-    }
-    if (!this.pendingSessionStore) {
+    if (this._disposed || !this.pendingSessionStore) {
       return { kind: 'none', reason: 'persistenceUnavailable' };
     }
     if (!this._host) {
@@ -166,12 +169,12 @@ export class SpareLink {
 
     for (const p of starts) {
       const result = paymentAbandoned({
-        linkToken: p.linkToken,
+        reference: p.reference,
         message: 'SpareLink has been disposed.',
         resolvedAtMs: Date.now(),
       });
       this._emitTerminal(result);
-      p.resolve(new SpareLinkSession({ linkToken: p.linkToken, result: Promise.resolve(result) }));
+      p.resolve(new SpareLinkSession({ reference: p.reference, result: Promise.resolve(result) }));
     }
     for (const p of redirects) {
       p.resolve(false);
@@ -207,6 +210,12 @@ export class SpareLink {
     this._emitTerminal(result);
   }
 
+  private _resolveImmediately(reference: string, message: string): SpareLinkSession {
+    const result = paymentAbandoned({ reference, message, resolvedAtMs: Date.now() });
+    this._emitTerminal(result);
+    return new SpareLinkSession({ reference, result: Promise.resolve(result) });
+  }
+
   private _emitTerminal(result: PaymentResult): void {
     switch (result.status) {
       case 'success':
@@ -224,11 +233,11 @@ export class SpareLink {
     }
   }
 
-  private async _hostStart(linkToken: string): Promise<SpareLinkSession> {
+  private async _hostStart(reference: string): Promise<SpareLinkSession> {
     const host = this._host;
     if (!host) {
       return new Promise<SpareLinkSession>((resolve) => {
-        this._pendingStarts.push({ linkToken, resolve });
+        this._pendingStarts.push({ reference, resolve });
       });
     }
 
@@ -236,21 +245,16 @@ export class SpareLink {
     const resultPromise = new Promise<PaymentResult>((resolve) => {
       resolveResult = resolve;
     });
-    const session = new SpareLinkSession({ linkToken, result: resultPromise });
 
     host.startFlow({
-      linkToken,
+      reference,
       resolve: (result) => {
         this._emitTerminal(result);
         resolveResult(result);
       },
-      onSessionLoaded: (linkSessionId) => {
-        session.updateLinkSessionId(linkSessionId);
-        this._events.emit(SpareLinkEvents.sessionLoaded(linkToken, linkSessionId));
-      },
     });
 
-    return session;
+    return new SpareLinkSession({ reference, result: resultPromise });
   }
 
   private _drainPending(host: SpareLinkHostDelegate): void {
@@ -259,7 +263,7 @@ export class SpareLink {
     const resumes = this._pendingResumes.splice(0);
 
     for (const p of starts) {
-      void this._hostStart(p.linkToken).then(p.resolve);
+      void this._hostStart(p.reference).then(p.resolve);
     }
     for (const p of redirects) {
       void host.handleRedirect(p.uri).then(p.resolve, () => p.resolve(false));
@@ -272,18 +276,6 @@ export class SpareLink {
   }
 }
 
-/** Map legacy recovery helper outcomes to Flutter-aligned {@link RecoveryResult}. */
-export function mapHostRecovery(
-  recovery: RecoveryResult | { kind: 'inProgress'; linkToken: string },
-): RecoveryResult {
-  if (recovery.kind === 'inProgress') {
-    return { kind: 'awaitingUser', linkToken: recovery.linkToken };
-  }
-  return recovery;
-}
-
-export function noRecovery(reason: NoRecoveryReason): RecoveryResult {
-  return { kind: 'none', reason };
+export function noRecovery(reason: NoRecoveryReason, reference?: string): RecoveryResult {
+  return reference ? { kind: 'none', reason, reference } : { kind: 'none', reason };
 }
-
-export { isSessionRecovered };

package/src/public/spare-link-session.ts

@@ -3,26 +3,14 @@ import type { PaymentResult } from './payment-result';
 /**
  * Handle for an in-flight or completed payment started via {@link SpareLink.start}.
  *
- * Mirrors Flutter's `SpareLinkSession` — `linkToken` is available immediately;
- * await `result` for the terminal outcome.
+ * `reference` is available immediately; await `result` for the terminal outcome.
  */
 export class SpareLinkSession {
-  readonly linkToken: string;
-  linkSessionId: string | undefined;
+  readonly reference: string;
   readonly result: Promise<PaymentResult>;
 
-  constructor(args: {
-    linkToken: string;
-    result: Promise<PaymentResult>;
-    linkSessionId?: string;
-  }) {
-    this.linkToken = args.linkToken;
-    this.linkSessionId = args.linkSessionId;
+  constructor(args: { reference: string; result: Promise<PaymentResult> }) {
+    this.reference = args.reference;
     this.result = args.result;
   }
-
-  /** Called internally when the server provides {@link linkSessionId}. */
-  updateLinkSessionId(value: string): void {
-    this.linkSessionId = value;
-  }
 }

package/src/public/spare-link.ts

@@ -1,2 +1,2 @@
-export { SpareLink, mapHostRecovery, noRecovery, isSessionRecovered } from './spare-link-instance';
+export { SpareLink, noRecovery } from './spare-link-instance';
 export type { SpareLinkOptions } from './spare-link-instance';