@tesser-payments/sdk-ts 0.1.0 → 0.2.0

package/README.md

@@ -24,7 +24,6 @@ const signer = new LocalSigner({
     privateKey: process.env.SIGNING_PRIVATE_KEY!,
     enclaveId: process.env.SIGNING_ENCLAVE_ID!,
   },
-  apiBaseUrl: 'https://api.tesser.xyz', // sandbox: https://api-sandbox.tesser.xyz
 });
 
 const { signature } = await signer.signCreateWallet({
@@ -50,8 +49,8 @@ const res = await fetch(`${API_BASE_URL}/v1/accounts/wallets`, {
 `signature` is `base64(JSON.stringify({ body, stamp }))` — drop it into the
 Tesser API request body as the documented `signature` field.
 
-`LocalSigner` requires the Tesser API base URL (`https://api.tesser.xyz` or
-`https://api-sandbox.tesser.xyz`); a trailing `/` or `/v1` is removed. Pass an
+`apiBaseUrl` is optional; pass it to use only that URL (`https://api.tesser.xyz`
+or `https://api-sandbox.tesser.xyz`; a trailing `/` or `/v1` is removed). Pass an
 optional `fetch` implementation to configure a proxy.
 
 `signCreateWallet` signs a wallet-creation request. For `stablecoin_ethereum`,
@@ -59,6 +58,13 @@ it first fetches the request to sign from the Tesser API and checks that it
 matches your parameters. The private key never leaves your process. Tesser
 currently supports managed wallets for `stablecoin_ethereum` only.
 
+`LocalSigner({ signing })` works with production and sandbox signing keys.
+Without `apiBaseUrl`, the first `stablecoin_ethereum` `signCreateWallet` tries
+production and, if production does not accept your signing key, sandbox, and
+remembers it for later calls. Set `apiBaseUrl` if your network allows only one
+Tesser host, or if you create a new signer per request (each new signer detects
+again). Send your own API requests to the environment of your signing key.
+
 **Private-key handling.** `signer.signing` exposes only `{ publicKey, enclaveId }`.
 The private key lives on the instance as an ECMA private field and is not
 reachable via property access, `console.log`, or `JSON.stringify`. The SDK still
@@ -141,7 +147,8 @@ the request `signCreateWallet` makes to Tesser for `stablecoin_ethereum`.
 `errors[]` (with `errorCode` for the first one). `TesserConnectionError`,
 `TesserTimeoutError`, and a `TesserAPIError` with status 429 or 5xx are safe to
 retry; a `TesserAPIError` with any other 4xx status fails the same way on
-retry.
+retry. Without `apiBaseUrl`, if neither production nor sandbox accepts your
+signing key, the `TesserAPIError` from production is thrown.
 
 Each error carries the original failure as `.cause` and can be discriminated via
 `instanceof` or the static `.is()` guard:

package/dist/index.js

@@ -21473,7 +21473,7 @@ async function stamp(keys, body) {
 }
 
 // src/internal/version.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.0";
 
 // src/signing/unsigned-payload.ts
 var UNSIGNED_PAYLOAD_PATH = "/v1/accounts/wallets/unsigned-payload";
@@ -21482,12 +21482,27 @@ var ETHEREUM_ADDRESS_FORMAT = "ADDRESS_FORMAT_ETHEREUM";
 var UNSIGNED_PAYLOAD_TIMEOUT_MS = 1e4;
 var LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 var MAX_FAILURE_CHAIN_DEPTH = 10;
-function createTesserApiConnection(options) {
+var PRODUCTION_API_BASE_URL = "https://api.tesser.xyz";
+var SANDBOX_API_BASE_URL = "https://api-sandbox.tesser.xyz";
+var DEFAULT_API_BASE_URLS = [PRODUCTION_API_BASE_URL, SANDBOX_API_BASE_URL];
+var STAMP_REJECTED_ERROR_CODE = "signing-4010";
+function createTesserApiConnection({
+  apiBaseUrl,
+  fetch: injectedFetch,
+  defaultBaseUrls = DEFAULT_API_BASE_URLS
+}) {
   return {
-    baseUrl: normalizeApiBaseUrl(options.apiBaseUrl),
-    fetch: resolveFetchImplementation(options.fetch)
+    fetch: resolveFetchImplementation(injectedFetch),
+    defaultBaseUrls,
+    resolvedBaseUrl: resolveExplicitApiBaseUrl(apiBaseUrl)
   };
 }
+function resolveExplicitApiBaseUrl(apiBaseUrl) {
+  if (apiBaseUrl === undefined) {
+    return;
+  }
+  return normalizeApiBaseUrl(apiBaseUrl);
+}
 function resolveFetchImplementation(injectedFetch) {
   if (injectedFetch !== undefined) {
     return injectedFetch;
@@ -21533,9 +21548,35 @@ function parseUrl(value) {
 }
 async function fetchCheckedCreateWalletAccountsBody(options) {
   const { api, signing, params } = options;
+  if (api.resolvedBaseUrl !== undefined) {
+    return fetchCheckedBodyFrom(api.resolvedBaseUrl, api.fetch, signing, params);
+  }
+  return detectEnvironmentAndFetchCheckedBody({ api, signing, params });
+}
+async function detectEnvironmentAndFetchCheckedBody(options) {
+  const { api, signing, params } = options;
+  let firstStampRejection;
+  for (const baseUrl of api.defaultBaseUrls) {
+    try {
+      const body = await fetchCheckedBodyFrom(baseUrl, api.fetch, signing, params);
+      api.resolvedBaseUrl = baseUrl;
+      return body;
+    } catch (error) {
+      if (!isStampRejected(error)) {
+        throw error;
+      }
+      firstStampRejection ??= error;
+    }
+  }
+  throw firstStampRejection;
+}
+function isStampRejected(error) {
+  return error instanceof TesserAPIError && error.status === 401 && error.errorCode === STAMP_REJECTED_ERROR_CODE;
+}
+async function fetchCheckedBodyFrom(baseUrl, fetchImplementation, signing, params) {
   const query = buildUnsignedPayloadQuery(signing, params);
   const stamped = await stamp({ publicKey: signing.publicKey, privateKey: signing.privateKey }, buildCanonicalUnsignedPayloadMessage(query));
-  const response = await sendUnsignedPayloadRequest(api, buildUnsignedPayloadUrl(api, query), stamped);
+  const response = await sendUnsignedPayloadRequest(fetchImplementation, buildUnsignedPayloadUrl(baseUrl, query), stamped);
   const body = parseUnsignedPayloadBody(response);
   assertUnsignedPayloadMatchesRequest(body, signing, params);
   return body;
@@ -21556,7 +21597,7 @@ function buildCanonicalUnsignedPayloadMessage(query) {
     timestampMs: query.timestampMs
   });
 }
-function buildUnsignedPayloadUrl(api, query) {
+function buildUnsignedPayloadUrl(baseUrl, query) {
   const queryEntries = [
     ["organizationId", query.organizationId],
     ["name", query.name],
@@ -21564,10 +21605,9 @@ function buildUnsignedPayloadUrl(api, query) {
     ["timestampMs", query.timestampMs]
   ];
   const queryString = queryEntries.map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join("&");
-  return `${api.baseUrl}${UNSIGNED_PAYLOAD_PATH}?${queryString}`;
+  return `${baseUrl}${UNSIGNED_PAYLOAD_PATH}?${queryString}`;
 }
-async function sendUnsignedPayloadRequest(api, url, stamped) {
-  const fetchImplementation = api.fetch;
+async function sendUnsignedPayloadRequest(fetchImplementation, url, stamped) {
   try {
     const response = await fetchImplementation(url, {
       method: "GET",

package/dist/internal/types.d.ts

@@ -50,10 +50,12 @@ export interface SignedStepResult {
 export interface LocalSignerOptions {
     signing: SigningConfig;
     /**
-     * Tesser API base URL: `https://api.tesser.xyz` in production,
-     * `https://api-sandbox.tesser.xyz` in sandbox. A trailing `/` or `/v1` is removed.
+     * Optional Tesser API base URL. Leave it unset and the signer finds the environment
+     * your signing key belongs to, production or sandbox. When set, only this URL is used:
+     * `https://api.tesser.xyz` in production, `https://api-sandbox.tesser.xyz` in sandbox.
+     * A trailing `/` or `/v1` is removed.
      */
-    apiBaseUrl: string;
+    apiBaseUrl?: string | undefined;
     /**
      * `fetch` implementation used for requests to Tesser. Inject one to configure a
      * proxy. Defaults to the global `fetch`.

package/dist/internal/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.1.0";
+export declare const SDK_VERSION = "0.2.0";

package/dist/signer.d.ts

@@ -12,15 +12,15 @@ export interface PublicSigningInfo {
  * Produces locally-signed activity payloads for Tesser API operations.
  *
  * Supports `signCreateWallet` and `signStep`. Construction validates that the
- * signing keys are non-blank and that `apiBaseUrl` is an https URL.
+ * signing keys are non-blank and that `apiBaseUrl`, if set, is an https URL.
  *
  * Key handling: the private key is stored in an ECMA private field (`#privateKey`)
  * and is not reachable via `signer.signing.privateKey` or any other public
  * surface. `signer.signing` exposes only `{ publicKey, enclaveId }`, so logging
  * `signer` or its `signing` property will not leak the private key.
  *
- * Thread-safety: stateless and reentrant. A single LocalSigner instance may
- * be shared across concurrent calls; the SDK never mutates internal state.
+ * Thread-safety: the only state is the environment remembered after the first
+ * Ethereum wallet request; a single LocalSigner may be shared across concurrent calls.
  */
 export declare class LocalSigner {
     #private;
@@ -39,7 +39,8 @@ export declare class LocalSigner {
      *   Tesser does not match your parameters.
      * @throws {TesserAPIError} if Tesser answers with an error status or an
      *   invalid response. Safe to retry for status 429 or 5xx; other 4xx statuses
-     *   fail the same way on retry.
+     *   fail the same way on retry. Without `apiBaseUrl`, if neither production nor
+     *   sandbox accepts your signing key, the error from production is thrown.
      * @throws {TesserConnectionError} if the request to Tesser fails at the
      *   network level. Safe to retry.
      * @throws {TesserTimeoutError} if the request to Tesser times out. Safe to retry.

package/dist/signing/unsigned-payload.d.ts

@@ -1,11 +1,13 @@
 import type { CreateWalletParams, SigningConfig } from '../internal/types.js';
 export interface TesserApiConnection {
-    baseUrl: string;
     fetch: typeof fetch;
+    defaultBaseUrls: readonly string[];
+    resolvedBaseUrl: string | undefined;
 }
-export declare function createTesserApiConnection(options: {
+export declare function createTesserApiConnection({ apiBaseUrl, fetch: injectedFetch, defaultBaseUrls, }: {
     apiBaseUrl: unknown;
     fetch: typeof fetch | undefined;
+    defaultBaseUrls?: readonly string[];
 }): TesserApiConnection;
 export declare function normalizeApiBaseUrl(apiBaseUrl: unknown): string;
 export declare function fetchCheckedCreateWalletAccountsBody(options: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tesser-payments/sdk-ts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK for Tesser API: sign signCreateWallet and signStep requests locally. No OAuth — bring your own client.",
   "type": "module",
   "exports": {