@invonetwork/web-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,357 @@
+'use strict';
+
+// src/shared/errors.ts
+var InvoError = class _InvoError extends Error {
+  constructor(args) {
+    super(args.message);
+    this.name = "InvoError";
+    this.code = args.code;
+    this.status = args.status;
+    this.body = args.body ?? null;
+    Object.setPrototypeOf(this, _InvoError.prototype);
+  }
+  /** True if this is the "recipient isn't passkey-enrolled, fall back to claim code" signal. */
+  get isReceiverNotEnrolled() {
+    return this.code === "receiver_not_enrolled_use_claim_code" || /receiver_not_enrolled_use_claim_code/i.test(this.message);
+  }
+  /** True if the session/SDK token has expired and the caller should re-mint + retry. */
+  get isTokenExpired() {
+    return this.code === "SDK_TOKEN_EXPIRED";
+  }
+};
+function errorFromResponse(status, body) {
+  let message = `INVO request failed (HTTP ${status})`;
+  let code;
+  if (body && typeof body === "object") {
+    const b = body;
+    if (typeof b["code"] === "string") code = b["code"];
+    if (typeof b["error"] === "string") message = b["error"];
+    else if (typeof b["message"] === "string") message = b["message"];
+  } else if (typeof body === "string" && body.trim()) {
+    message = body;
+  }
+  return new InvoError({ message, code, status, body });
+}
+
+// src/shared/http.ts
+var DEFAULT_TIMEOUT = 3e4;
+function assertSecureBaseUrl(baseUrl) {
+  let u;
+  try {
+    u = new URL(baseUrl);
+  } catch {
+    throw new Error(`Invalid baseUrl: ${baseUrl}`);
+  }
+  const isLocal = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]";
+  if (u.protocol === "https:" || u.protocol === "http:" && isLocal) return;
+  throw new Error(
+    `baseUrl must use https:// (got "${u.protocol}//"). Plaintext would expose the token/secret on the wire.`
+  );
+}
+var Http = class {
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT;
+    const f = opts.fetchImpl ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new Error(
+        "No fetch implementation available. Use Node >=18, or pass `fetch` in the config."
+      );
+    }
+    this.fetchImpl = f;
+    this.userAgent = opts.userAgent;
+  }
+  async post(path, body, auth) {
+    return this.request("POST", path, body, auth);
+  }
+  async get(path, auth) {
+    return this.request("GET", path, void 0, auth);
+  }
+  authHeaders(auth) {
+    switch (auth.kind) {
+      case "game-secret":
+        return { "X-Game-Secret-Key": auth.secret };
+      case "bearer":
+        return { Authorization: `Bearer ${auth.token}` };
+      case "none":
+        return {};
+    }
+  }
+  async request(method, path, body, auth) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      Accept: "application/json",
+      ...this.authHeaders(auth)
+    };
+    if (this.userAgent) headers["User-Agent"] = this.userAgent;
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      throw new InvoError({
+        message: err instanceof Error && err.name === "AbortError" ? `Request to ${path} timed out after ${this.timeoutMs}ms` : `Network error calling ${path}: ${err?.message ?? err}`,
+        status: 0,
+        body: null
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let parsed = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (!res.ok) throw errorFromResponse(res.status, parsed);
+    return parsed ?? {};
+  }
+};
+
+// src/shared/webauthn.ts
+function b64urlToBuffer(value) {
+  const pad = value.length % 4 === 0 ? "" : "=".repeat(4 - value.length % 4);
+  const b64 = value.replace(/-/g, "+").replace(/_/g, "/") + pad;
+  const bin = atob(b64);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes.buffer;
+}
+function bufferToB64url(buf) {
+  const bytes = new Uint8Array(buf);
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function descriptorsToBinary(list) {
+  return (list ?? []).map((d) => {
+    const out = {
+      id: b64urlToBuffer(d.id),
+      type: d.type
+    };
+    if (d.transports) out.transports = d.transports;
+    return out;
+  });
+}
+function toCreationOptions(json) {
+  const opts = {
+    ...json,
+    challenge: b64urlToBuffer(json["challenge"]),
+    user: {
+      ...json["user"],
+      id: b64urlToBuffer(json["user"].id)
+    }
+  };
+  if (json["excludeCredentials"]) {
+    opts.excludeCredentials = descriptorsToBinary(json["excludeCredentials"]);
+  }
+  return opts;
+}
+function toRequestOptions(json) {
+  const opts = {
+    ...json,
+    challenge: b64urlToBuffer(json["challenge"])
+  };
+  if (json["allowCredentials"]) {
+    opts.allowCredentials = descriptorsToBinary(json["allowCredentials"]);
+  }
+  return opts;
+}
+function registrationToJSON(cred) {
+  const r = cred.response;
+  return {
+    id: cred.id,
+    rawId: bufferToB64url(cred.rawId),
+    type: cred.type,
+    authenticatorAttachment: cred.authenticatorAttachment ?? void 0,
+    clientExtensionResults: cred.getClientExtensionResults(),
+    response: {
+      clientDataJSON: bufferToB64url(r.clientDataJSON),
+      attestationObject: bufferToB64url(r.attestationObject),
+      transports: typeof r.getTransports === "function" ? r.getTransports() : void 0
+    }
+  };
+}
+function assertionToJSON(cred) {
+  const r = cred.response;
+  return {
+    id: cred.id,
+    rawId: bufferToB64url(cred.rawId),
+    type: cred.type,
+    authenticatorAttachment: cred.authenticatorAttachment ?? void 0,
+    clientExtensionResults: cred.getClientExtensionResults(),
+    response: {
+      clientDataJSON: bufferToB64url(r.clientDataJSON),
+      authenticatorData: bufferToB64url(r.authenticatorData),
+      signature: bufferToB64url(r.signature),
+      userHandle: r.userHandle ? bufferToB64url(r.userHandle) : null
+    }
+  };
+}
+
+// src/index.ts
+var InvoClient = class {
+  constructor(config) {
+    if (!config.token) throw new Error("InvoClient requires a player `token`.");
+    if (!config.baseUrl) throw new Error("InvoClient requires a `baseUrl`.");
+    assertSecureBaseUrl(config.baseUrl);
+    this.http = new Http({
+      baseUrl: config.baseUrl,
+      timeoutMs: config.timeoutMs,
+      fetchImpl: config.fetch
+      // Browser: do NOT set User-Agent (forbidden header); the browser's own UA is fine.
+    });
+    this.auth = { kind: "bearer", token: config.token };
+    this.refreshToken = config.refreshToken;
+  }
+  assertWebAuthn() {
+    if (typeof navigator === "undefined" || !navigator.credentials) {
+      throw new Error("WebAuthn is not available in this environment (browser required).");
+    }
+  }
+  /** Enroll a passkey for the token's identity (register/begin -> create() -> register/complete). */
+  async enrollPasskey() {
+    this.assertWebAuthn();
+    return this.withTokenRetry(async () => {
+      const options = await this.post(
+        "/api/sdk/webauthn/register/begin"
+      );
+      const cred = await navigator.credentials.create({
+        publicKey: toCreationOptions(options)
+      });
+      if (!cred) throw new Error("Passkey creation was cancelled or returned no credential.");
+      const raw = await this.post(
+        "/api/sdk/webauthn/register/complete",
+        { credential: registrationToJSON(cred) }
+      );
+      return { status: String(raw["status"] ?? ""), device: raw["device"] ?? null, raw };
+    });
+  }
+  /** Approve a SEND with the player's passkey. */
+  async approveSend(transactionId) {
+    return this.approve("send", transactionId);
+  }
+  /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
+  async approveTransfer(transactionId) {
+    return this.approve("transfers", transactionId);
+  }
+  /** Recipient self-claims a SEND with their passkey. */
+  async confirmReceiptSend(transactionId) {
+    return this.confirmReceipt("send", transactionId);
+  }
+  /** Recipient self-claims a TRANSFER with their passkey. */
+  async confirmReceiptTransfer(transactionId) {
+    return this.confirmReceipt("transfers", transactionId);
+  }
+  /**
+   * Interchangeable methods (§4.6): prove an *already-enrolled* method (e.g. the
+   * INVO app device key) to authorize adding a new partner passkey. The returned
+   * single-use grant lets a subsequent enrollPasskey() succeed instead of being
+   * blocked with ENROLLMENT_REQUIRES_PROOF.
+   *
+   * begin -> navigator.credentials.get() -> complete with { link_id, webauthn_assertion }.
+   */
+  async linkDevice(linkId) {
+    if (!linkId) throw new Error("linkDevice requires a `linkId`.");
+    return this.withTokenRetry(async () => {
+      const assertion = await this.runAssertion("/api/sdk/device/link/webauthn/begin", {
+        link_id: linkId
+      });
+      const raw = await this.post(
+        "/api/sdk/device/link/webauthn/complete",
+        { link_id: linkId, webauthn_assertion: assertion }
+      );
+      return { status: String(raw["status"] ?? ""), raw };
+    });
+  }
+  // --- internals ---
+  /** POST with the current player token. Token-expiry retry is handled one level
+   *  up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
+  async post(path, body) {
+    return this.http.post(path, body, this.auth);
+  }
+  /**
+   * Run a whole flow, retrying it ONCE if any call fails with SDK_TOKEN_EXPIRED
+   * and a `refreshToken` hook is configured. We re-run the entire begin→get→
+   * complete ceremony (not just the failed call) so the retry always uses a fresh,
+   * unconsumed challenge — never replaying a single-use WebAuthn assertion (§4.4).
+   * The refresh is single-flighted so concurrent expiries trigger one re-mint.
+   */
+  async withTokenRetry(run) {
+    try {
+      return await run();
+    } catch (err) {
+      if (err instanceof InvoError && err.isTokenExpired && await this.tryRefresh()) {
+        return await run();
+      }
+      throw err;
+    }
+  }
+  async tryRefresh() {
+    if (!this.refreshToken) return false;
+    if (!this.refreshInFlight) {
+      this.refreshInFlight = Promise.resolve(this.refreshToken()).finally(() => {
+        this.refreshInFlight = void 0;
+      });
+    }
+    const fresh = await this.refreshInFlight;
+    if (!fresh) return false;
+    this.auth = { kind: "bearer", token: fresh };
+    return true;
+  }
+  async runAssertion(beginPath, beginBody) {
+    this.assertWebAuthn();
+    const options = await this.post(beginPath, beginBody);
+    const cred = await navigator.credentials.get({
+      publicKey: toRequestOptions(options)
+    });
+    if (!cred) throw new Error("Passkey assertion was cancelled or returned no credential.");
+    return assertionToJSON(cred);
+  }
+  async approve(flow, transactionId) {
+    const id = encodeURIComponent(transactionId);
+    return this.withTokenRetry(async () => {
+      const assertion = await this.runAssertion(`/api/sdk/${flow}/${id}/approve/webauthn/begin`);
+      const raw = await this.post(
+        `/api/sdk/${flow}/${id}/approve`,
+        { webauthn_assertion: assertion }
+      );
+      return {
+        status: String(raw["status"] ?? ""),
+        next: String(raw["next"] ?? ""),
+        transactionId: String(raw["transaction_id"] ?? transactionId),
+        claimCode: raw["claim_code"],
+        claimCodeExpiresAt: raw["claim_code_expires_at"],
+        raw
+      };
+    });
+  }
+  async confirmReceipt(flow, transactionId) {
+    const id = encodeURIComponent(transactionId);
+    return this.withTokenRetry(async () => {
+      const assertion = await this.runAssertion(
+        `/api/sdk/${flow}/${id}/confirm-receipt/webauthn/begin`
+      );
+      const raw = await this.post(
+        `/api/sdk/${flow}/${id}/confirm-receipt`,
+        { webauthn_assertion: assertion }
+      );
+      return { status: String(raw["status"] ?? ""), raw };
+    });
+  }
+};
+
+exports.InvoClient = InvoClient;
+exports.InvoError = InvoError;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-B7rVID2r.cjs';
+export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.cjs';
+
+declare class InvoClient {
+    private readonly http;
+    private auth;
+    private readonly refreshToken;
+    /** In-flight refresh, shared so concurrent expiries trigger a single re-mint. */
+    private refreshInFlight;
+    constructor(config: ClientConfig);
+    private assertWebAuthn;
+    /** Enroll a passkey for the token's identity (register/begin -> create() -> register/complete). */
+    enrollPasskey(): Promise<{
+        status: string;
+        device: unknown;
+        raw: Record<string, unknown>;
+    }>;
+    /** Approve a SEND with the player's passkey. */
+    approveSend(transactionId: string): Promise<ApproveResult>;
+    /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
+    approveTransfer(transactionId: string): Promise<ApproveResult>;
+    /** Recipient self-claims a SEND with their passkey. */
+    confirmReceiptSend(transactionId: string): Promise<ConfirmReceiptResult>;
+    /** Recipient self-claims a TRANSFER with their passkey. */
+    confirmReceiptTransfer(transactionId: string): Promise<ConfirmReceiptResult>;
+    /**
+     * Interchangeable methods (§4.6): prove an *already-enrolled* method (e.g. the
+     * INVO app device key) to authorize adding a new partner passkey. The returned
+     * single-use grant lets a subsequent enrollPasskey() succeed instead of being
+     * blocked with ENROLLMENT_REQUIRES_PROOF.
+     *
+     * begin -> navigator.credentials.get() -> complete with { link_id, webauthn_assertion }.
+     */
+    linkDevice(linkId: string): Promise<LinkDeviceResult>;
+    /** POST with the current player token. Token-expiry retry is handled one level
+     *  up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
+    private post;
+    /**
+     * Run a whole flow, retrying it ONCE if any call fails with SDK_TOKEN_EXPIRED
+     * and a `refreshToken` hook is configured. We re-run the entire begin→get→
+     * complete ceremony (not just the failed call) so the retry always uses a fresh,
+     * unconsumed challenge — never replaying a single-use WebAuthn assertion (§4.4).
+     * The refresh is single-flighted so concurrent expiries trigger one re-mint.
+     */
+    private withTokenRetry;
+    private tryRefresh;
+    private runAssertion;
+    private approve;
+    private confirmReceipt;
+}
+
+export { ApproveResult, ClientConfig, ConfirmReceiptResult, InvoClient, LinkDeviceResult };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-B7rVID2r.js';
+export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.js';
+
+declare class InvoClient {
+    private readonly http;
+    private auth;
+    private readonly refreshToken;
+    /** In-flight refresh, shared so concurrent expiries trigger a single re-mint. */
+    private refreshInFlight;
+    constructor(config: ClientConfig);
+    private assertWebAuthn;
+    /** Enroll a passkey for the token's identity (register/begin -> create() -> register/complete). */
+    enrollPasskey(): Promise<{
+        status: string;
+        device: unknown;
+        raw: Record<string, unknown>;
+    }>;
+    /** Approve a SEND with the player's passkey. */
+    approveSend(transactionId: string): Promise<ApproveResult>;
+    /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
+    approveTransfer(transactionId: string): Promise<ApproveResult>;
+    /** Recipient self-claims a SEND with their passkey. */
+    confirmReceiptSend(transactionId: string): Promise<ConfirmReceiptResult>;
+    /** Recipient self-claims a TRANSFER with their passkey. */
+    confirmReceiptTransfer(transactionId: string): Promise<ConfirmReceiptResult>;
+    /**
+     * Interchangeable methods (§4.6): prove an *already-enrolled* method (e.g. the
+     * INVO app device key) to authorize adding a new partner passkey. The returned
+     * single-use grant lets a subsequent enrollPasskey() succeed instead of being
+     * blocked with ENROLLMENT_REQUIRES_PROOF.
+     *
+     * begin -> navigator.credentials.get() -> complete with { link_id, webauthn_assertion }.
+     */
+    linkDevice(linkId: string): Promise<LinkDeviceResult>;
+    /** POST with the current player token. Token-expiry retry is handled one level
+     *  up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
+    private post;
+    /**
+     * Run a whole flow, retrying it ONCE if any call fails with SDK_TOKEN_EXPIRED
+     * and a `refreshToken` hook is configured. We re-run the entire begin→get→
+     * complete ceremony (not just the failed call) so the retry always uses a fresh,
+     * unconsumed challenge — never replaying a single-use WebAuthn assertion (§4.4).
+     * The refresh is single-flighted so concurrent expiries trigger one re-mint.
+     */
+    private withTokenRetry;
+    private tryRefresh;
+    private runAssertion;
+    private approve;
+    private confirmReceipt;
+}
+
+export { ApproveResult, ClientConfig, ConfirmReceiptResult, InvoClient, LinkDeviceResult };