@pymthouse/builder-sdk 0.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PymtHouse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @pymthouse/builder-sdk
+
+Source repository: [pymthouse/builder-sdk](https://github.com/pymthouse/builder-sdk). The npm package name is `@pymthouse/builder-sdk`.
+
+TypeScript client for the **PymtHouse Builder API**, **Usage API**, and **OIDC issuer** surfaces.
+
+OAuth/OIDC protocol calls use **[oauth4webapi](https://github.com/panva/oauth4webapi)** (OpenID-certified relying-party implementation). PymtHouse-specific REST paths and helpers live in `PmtHouseClient`.
+
+## Install
+
+```bash
+pnpm add @pymthouse/builder-sdk
+```
+
+## Quick start
+
+```ts
+import { PmtHouseClient } from "@pymthouse/builder-sdk";
+import {
+  createPmtHouseClientFromEnv,
+  getPymthouseBaseUrl,
+} from "@pymthouse/builder-sdk/env";
+
+const client = createPmtHouseClientFromEnv();
+const base = getPymthouseBaseUrl();
+const discovery = await client.getDiscovery();
+```
+
+Or construct explicitly:
+
+```ts
+import { PmtHouseClient } from "@pymthouse/builder-sdk";
+
+const client = new PmtHouseClient({
+  issuerUrl: process.env.PYMTHOUSE_ISSUER_URL!,
+  publicClientId: process.env.PYMTHOUSE_PUBLIC_CLIENT_ID!,
+  m2mClientId: process.env.PYMTHOUSE_M2M_CLIENT_ID!,
+  m2mClientSecret: process.env.PYMTHOUSE_M2M_CLIENT_SECRET!,
+  allowInsecureHttp: process.env.PYMTHOUSE_ISSUER_URL?.startsWith("http:"),
+});
+```
+
+## User tokens: short-lived JWT or long-lived signer session
+
+Use `mintUserAccessToken()` when your backend needs the short-lived
+Builder-minted user JWT directly:
+
+```ts
+const userJwt = await client.mintUserAccessToken({
+  externalUserId: "naap-user-123",
+  scope: "sign:job",
+});
+```
+
+Use `mintUserSignerSessionToken()` when you want the user-facing opaque
+`pmth_...` signer session. This first mints the short-lived user JWT, then
+performs the RFC 8693 token exchange with the confidential M2M client:
+
+```ts
+const signerSession = await client.mintUserSignerSessionToken({
+  externalUserId: "naap-user-123",
+  scope: "sign:job",
+});
+```
+
+For advanced flows that already have a user JWT, call
+`exchangeForSignerSession({ userJwt })` directly.
+
+## Subpath exports
+
+| Import | Purpose |
+|--------|---------|
+| `@pymthouse/builder-sdk` | `PmtHouseClient`, discovery cache, errors, usage aggregation helpers |
+| `@pymthouse/builder-sdk/format` | Wei formatting for Usage API |
+| `@pymthouse/builder-sdk/env` | `createPmtHouseClientFromEnv`, `getPymthouseBaseUrl` |
+| `@pymthouse/builder-sdk/device` | RFC 8628 `pollDeviceToken` |
+| `@pymthouse/builder-sdk/verify` | RFC 9068 `verifyJwt` |
+
+## Usage API: duplicate `byUser` rows
+
+When `getUsage({ groupBy: "user" })` returns multiple `byUser` rows with the same
+`externalUserId`, sum them with `summarizeUsageForExternalUser` (or
+`aggregateUsageByExternalUserId` on `byUser` alone):
+
+```ts
+import { summarizeUsageForExternalUser } from "@pymthouse/builder-sdk";
+
+const usage = await client.getUsage({ groupBy: "user", startDate, endDate });
+const summary = summarizeUsageForExternalUser(usage, externalUserId);
+// summary.requestCount, summary.feeWei (wei string)
+```
+
+## Usage API: pipeline/model grouping
+
+When `getUsage({ groupBy: "pipeline_model", startDate, endDate, userId })` returns
+`byPipelineModel`, use `listUsageByPipelineModel` for a stable-sorted copy. Pass
+the optional `gatewayRequestId` filter to scope results to a single upstream
+gateway request:
+
+```ts
+import { listUsageByPipelineModel } from "@pymthouse/builder-sdk";
+
+const usage = await client.getUsage({
+  groupBy: "pipeline_model",
+  startDate,
+  endDate,
+  userId: internalUserId,
+  gatewayRequestId, // optional: filter to a single gateway request
+});
+const rows = listUsageByPipelineModel(usage);
+```
+
+## Documentation
+
+Authoritative API behavior: [PymtHouse `docs/builder-api.md`](https://github.com/pymthouse/pymthouse/blob/main/docs/builder-api.md).
+
+## Server-only: `createPmtHouseClientFromEnv` / `@pymthouse/builder-sdk/env`
+
+M2M credentials are **confidential**. The `env` entry point:
+
+1. **Throws as soon as the module loads in a browser** (detects `globalThis.window`), so a mistaken client import fails immediately instead of silently bundling secrets.
+2. Does **not** stop someone from putting `m2mClientSecret` in `new PmtHouseClient({ ... })` in client code—you still must not do that.
+
+**Next.js — build-time guard (optional):** in a file that is only used from the server, add the official marker so the bundler errors instead of shipping the module to the client:
+
+```ts
+// e.g. lib/pymthouse-server.ts
+import "server-only";
+
+export {
+  createPmtHouseClientFromEnv,
+  getPymthouseBaseUrl,
+} from "@pymthouse/builder-sdk/env";
+```
+
+Import `createPmtHouseClientFromEnv` only from that wrapper (or from Route Handlers / Server Actions directly).
+
+## Next.js (monorepo) consumption
+
+When the SDK lives as a sibling folder (e.g. `../node-pymt-sdk`), enable `experimental.externalDir` in `next.config` and re-export from a small `lib` shim that points at `../../node-pymt-sdk` (see the `website` app in this org). Published installs from npm use the package name directly without shims.
+
+## License
+
+MIT

package/dist/device.cjs

@@ -0,0 +1,246 @@
+'use strict';
+
+var oauth4webapi = require('oauth4webapi');
+
+// src/device.ts
+
+// src/errors.ts
+var PmtHouseError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(message, {
+    status = 500,
+    code = "pymthouse_error",
+    details
+  } = {}) {
+    super(message);
+    this.name = "PmtHouseError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/string-utils.ts
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end--;
+  }
+  return value.slice(0, end);
+}
+
+// src/discovery.ts
+var CACHE_TTL_MS = 5 * 60 * 1e3;
+var discoveryCache = /* @__PURE__ */ new Map();
+function normalizedIssuerKey(issuerUrl) {
+  return stripTrailingSlashes(issuerUrl);
+}
+async function loadAuthorizationServer(issuerUrl, fetchImpl, options = {}) {
+  const key = normalizedIssuerKey(issuerUrl);
+  const now = Date.now();
+  const cached = discoveryCache.get(key);
+  if (!options.force && cached && now - cached.fetchedAt < CACHE_TTL_MS) {
+    return cached.as;
+  }
+  const issuerIdentifier = new URL(key);
+  const discoveryOpts = {
+    algorithm: "oidc",
+    [oauth4webapi.customFetch]: fetchImpl
+  };
+  if (options.allowInsecureHttp) {
+    discoveryOpts[oauth4webapi.allowInsecureRequests] = true;
+  }
+  let response;
+  try {
+    response = await oauth4webapi.discoveryRequest(issuerIdentifier, discoveryOpts);
+  } catch (e) {
+    throw mapDiscoveryNetworkError(e);
+  }
+  let as;
+  try {
+    as = await oauth4webapi.processDiscoveryResponse(issuerIdentifier, response);
+  } catch (e) {
+    throw mapOAuthDiscoveryError(e);
+  }
+  discoveryCache.set(key, { as, fetchedAt: now });
+  return as;
+}
+function mapOAuthDiscoveryError(error) {
+  if (error instanceof PmtHouseError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new PmtHouseError(error.message, {
+      status: 500,
+      code: "oidc_discovery_invalid",
+      details: { cause: error.cause }
+    });
+  }
+  return new PmtHouseError("OIDC discovery failed", {
+    status: 500,
+    code: "oidc_discovery_invalid"
+  });
+}
+function mapDiscoveryNetworkError(error) {
+  if (error instanceof PmtHouseError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new PmtHouseError(`Failed to load OIDC discovery: ${error.message}`, {
+      status: 502,
+      code: "oidc_discovery_failed"
+    });
+  }
+  return new PmtHouseError("Failed to load OIDC discovery", {
+    status: 502,
+    code: "oidc_discovery_failed"
+  });
+}
+function mapOAuthError(error) {
+  if (error instanceof PmtHouseError) {
+    return error;
+  }
+  if (error instanceof oauth4webapi.ResponseBodyError) {
+    const cause = error.cause;
+    const description = typeof error.error_description === "string" ? error.error_description : error.message;
+    const details = { ...cause };
+    if (typeof cause.error_uri === "string") {
+      details.error_uri = cause.error_uri;
+    }
+    return new PmtHouseError(description, {
+      status: error.status,
+      code: error.error,
+      details
+    });
+  }
+  if (error instanceof oauth4webapi.OperationProcessingError) {
+    return new PmtHouseError(error.message, {
+      status: 502,
+      code: error.code ?? "oauth_processing_error",
+      details: { cause: error.cause }
+    });
+  }
+  if (error instanceof Error) {
+    return new PmtHouseError(error.message, {
+      status: 500,
+      code: "unexpected_error"
+    });
+  }
+  return new PmtHouseError("Unexpected error", {
+    status: 500,
+    code: "unexpected_error"
+  });
+}
+
+// src/device.ts
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        reject(
+          signal.reason instanceof Error ? signal.reason : new Error(typeof signal.reason === "string" ? signal.reason : "Aborted")
+        );
+      },
+      { once: true }
+    );
+  });
+}
+async function pollDeviceToken(options) {
+  const fetchImpl = options.fetch ?? fetch;
+  const as = await loadAuthorizationServer(options.issuerUrl, fetchImpl, {
+    allowInsecureHttp: options.allowInsecureHttp
+  });
+  if (!as.device_authorization_endpoint) {
+    throw new PmtHouseError(
+      "Authorization server metadata has no device_authorization_endpoint",
+      { status: 400, code: "unsupported_grant" }
+    );
+  }
+  const client = { client_id: options.clientId };
+  const params = new URLSearchParams();
+  if (options.scope) {
+    params.set("scope", options.scope);
+  }
+  const httpOpts = {
+    [oauth4webapi.customFetch]: fetchImpl
+  };
+  if (options.allowInsecureHttp) {
+    httpOpts[oauth4webapi.allowInsecureRequests] = true;
+  }
+  let deviceResponse;
+  try {
+    deviceResponse = await oauth4webapi.deviceAuthorizationRequest(
+      as,
+      client,
+      oauth4webapi.None(),
+      params,
+      httpOpts
+    );
+  } catch (e) {
+    throw mapOAuthError(e);
+  }
+  let dar;
+  try {
+    dar = await oauth4webapi.processDeviceAuthorizationResponse(as, client, deviceResponse);
+  } catch (e) {
+    throw mapOAuthError(e);
+  }
+  options.onUserCode?.({
+    userCode: dar.user_code,
+    verificationUri: dar.verification_uri,
+    verificationUriComplete: dar.verification_uri_complete,
+    expiresIn: dar.expires_in,
+    intervalSeconds: dar.interval
+  });
+  let pollIntervalMs = (dar.interval ?? 5) * 1e3;
+  const deadline = Date.now() + dar.expires_in * 1e3;
+  let firstPoll = true;
+  while (Date.now() < deadline) {
+    if (options.signal?.aborted) {
+      throw options.signal.reason instanceof Error ? options.signal.reason : new Error("Aborted");
+    }
+    if (!firstPoll) {
+      await sleep(pollIntervalMs, options.signal);
+    }
+    firstPoll = false;
+    let tokenResponse;
+    try {
+      tokenResponse = await oauth4webapi.deviceCodeGrantRequest(
+        as,
+        client,
+        oauth4webapi.None(),
+        dar.device_code,
+        httpOpts
+      );
+    } catch (e) {
+      throw mapOAuthError(e);
+    }
+    try {
+      return await oauth4webapi.processDeviceCodeResponse(as, client, tokenResponse);
+    } catch (e) {
+      if (e instanceof oauth4webapi.ResponseBodyError) {
+        if (e.error === "authorization_pending") {
+          continue;
+        }
+        if (e.error === "slow_down") {
+          pollIntervalMs += 5e3;
+          continue;
+        }
+      }
+      throw mapOAuthError(e);
+    }
+  }
+  throw new PmtHouseError("Device authorization expired before completion", {
+    status: 408,
+    code: "device_flow_expired"
+  });
+}
+
+exports.pollDeviceToken = pollDeviceToken;
+//# sourceMappingURL=device.cjs.map
+//# sourceMappingURL=device.cjs.map

package/dist/device.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/string-utils.ts","../src/discovery.ts","../src/oauth-map.ts","../src/device.ts"],"names":["customFetch","allowInsecureRequests","discoveryRequest","processDiscoveryResponse","ResponseBodyError","OperationProcessingError","deviceAuthorizationRequest","None","processDeviceAuthorizationResponse","deviceCodeGrantRequest","processDeviceCodeResponse"],"mappings":"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","file":"device.cjs","sourcesContent":["export class PmtHouseError extends Error {\n  readonly status: number;\n  readonly code: string;\n  readonly details?: unknown;\n\n  constructor(\n    message: string,\n    {\n      status = 500,\n      code = \"pymthouse_error\",\n      details,\n    }: {\n      status?: number;\n      code?: string;\n      details?: unknown;\n    } = {},\n  ) {\n    super(message);\n    this.name = \"PmtHouseError\";\n    this.status = status;\n    this.code = code;\n    this.details = details;\n  }\n}\n\nexport function toPmtHouseError(\n  error: unknown,\n  fallbackMessage: string,\n): PmtHouseError {\n  if (error instanceof PmtHouseError) {\n    return error;\n  }\n\n  if (error instanceof Error) {\n    return new PmtHouseError(error.message || fallbackMessage, {\n      code: \"unexpected_error\",\n      status: 500,\n    });\n  }\n\n  return new PmtHouseError(fallbackMessage, {\n    code: \"unexpected_error\",\n    status: 500,\n  });\n}\n","/** Removes trailing `/` without regex (linear time). */\nexport function stripTrailingSlashes(value: string): string {\n  let end = value.length;\n  while (end > 0 && value.charCodeAt(end - 1) === 47) {\n    end--;\n  }\n  return value.slice(0, end);\n}\n","import {\n  allowInsecureRequests,\n  customFetch,\n  discoveryRequest,\n  processDiscoveryResponse,\n  type AuthorizationServer,\n} from \"oauth4webapi\";\nimport { PmtHouseError } from \"./errors.js\";\nimport { stripTrailingSlashes } from \"./string-utils.js\";\nimport type { FetchLike, OidcDiscoveryDocument } from \"./types.js\";\n\nexport function authorizationServerToOidcDocument(as: AuthorizationServer): OidcDiscoveryDocument {\n  const tokenEndpoint = as.token_endpoint;\n  const jwksUri = as.jwks_uri;\n  if (!tokenEndpoint || !jwksUri) {\n    throw new PmtHouseError(\"OIDC discovery document is missing token_endpoint or jwks_uri\", {\n      status: 500,\n      code: \"oidc_discovery_invalid\",\n    });\n  }\n  return {\n    issuer: as.issuer,\n    authorization_endpoint: as.authorization_endpoint ?? \"\",\n    token_endpoint: tokenEndpoint,\n    jwks_uri: jwksUri,\n    userinfo_endpoint: as.userinfo_endpoint,\n    device_authorization_endpoint: as.device_authorization_endpoint,\n  };\n}\n\nconst CACHE_TTL_MS = 5 * 60 * 1000;\n\ntype CacheEntry = {\n  as: AuthorizationServer;\n  fetchedAt: number;\n};\n\nconst discoveryCache = new Map<string, CacheEntry>();\n\nfunction normalizedIssuerKey(issuerUrl: string): string {\n  return stripTrailingSlashes(issuerUrl);\n}\n\nexport interface LoadAuthorizationServerOptions {\n  force?: boolean;\n  allowInsecureHttp?: boolean;\n}\n\n/**\n * Loads OIDC discovery metadata via oauth4webapi (RFC 8414 / OIDC Discovery), with a 5-minute cache.\n */\nexport async function loadAuthorizationServer(\n  issuerUrl: string,\n  fetchImpl: FetchLike,\n  options: LoadAuthorizationServerOptions = {},\n): Promise<AuthorizationServer> {\n  const key = normalizedIssuerKey(issuerUrl);\n  const now = Date.now();\n  const cached = discoveryCache.get(key);\n\n  if (!options.force && cached && now - cached.fetchedAt < CACHE_TTL_MS) {\n    return cached.as;\n  }\n\n  const issuerIdentifier = new URL(key);\n  const discoveryOpts: Parameters<typeof discoveryRequest>[1] = {\n    algorithm: \"oidc\",\n    [customFetch]: fetchImpl,\n  };\n  if (options.allowInsecureHttp) {\n    discoveryOpts[allowInsecureRequests] = true;\n  }\n\n  let response: Response;\n  try {\n    response = await discoveryRequest(issuerIdentifier, discoveryOpts);\n  } catch (e) {\n    throw mapDiscoveryNetworkError(e);\n  }\n\n  let as: AuthorizationServer;\n  try {\n    as = await processDiscoveryResponse(issuerIdentifier, response);\n  } catch (e) {\n    throw mapOAuthDiscoveryError(e);\n  }\n\n  discoveryCache.set(key, { as, fetchedAt: now });\n  return as;\n}\n\nexport async function fetchDiscoveryDocument(\n  issuerUrl: string,\n  fetchImpl: FetchLike,\n  options: LoadAuthorizationServerOptions = {},\n): Promise<OidcDiscoveryDocument> {\n  const as = await loadAuthorizationServer(issuerUrl, fetchImpl, options);\n  return authorizationServerToOidcDocument(as);\n}\n\nexport function clearDiscoveryCache(issuerUrl?: string): void {\n  if (!issuerUrl) {\n    discoveryCache.clear();\n    return;\n  }\n  discoveryCache.delete(normalizedIssuerKey(issuerUrl));\n}\n\nfunction mapOAuthDiscoveryError(error: unknown): PmtHouseError {\n  if (error instanceof PmtHouseError) {\n    return error;\n  }\n  if (error instanceof Error) {\n    return new PmtHouseError(error.message, {\n      status: 500,\n      code: \"oidc_discovery_invalid\",\n      details: { cause: error.cause },\n    });\n  }\n  return new PmtHouseError(\"OIDC discovery failed\", {\n    status: 500,\n    code: \"oidc_discovery_invalid\",\n  });\n}\n\nfunction mapDiscoveryNetworkError(error: unknown): PmtHouseError {\n  if (error instanceof PmtHouseError) {\n    return error;\n  }\n  if (error instanceof Error) {\n    return new PmtHouseError(`Failed to load OIDC discovery: ${error.message}`, {\n      status: 502,\n      code: \"oidc_discovery_failed\",\n    });\n  }\n  return new PmtHouseError(\"Failed to load OIDC discovery\", {\n    status: 502,\n    code: \"oidc_discovery_failed\",\n  });\n}\n","import { type Client, OperationProcessingError, ResponseBodyError } from \"oauth4webapi\";\nimport { PmtHouseError } from \"./errors.js\";\nimport type { ClientCredentialsTokenResponse, TokenExchangeResponse } from \"./types.js\";\n\nconst ACCEPTED_ISSUED_TOKEN_TYPES = new Set([\n  \"urn:ietf:params:oauth:token-type:access_token\",\n  \"urn:pmth:token-type:remote-signer-session\",\n]);\n\nexport function mapOAuthError(error: unknown): PmtHouseError {\n  if (error instanceof PmtHouseError) {\n    return error;\n  }\n\n  if (error instanceof ResponseBodyError) {\n    const cause = error.cause as Record<string, unknown>;\n    const description =\n      typeof error.error_description === \"string\"\n        ? error.error_description\n        : error.message;\n    const details: Record<string, unknown> = { ...cause };\n    if (typeof cause.error_uri === \"string\") {\n      details.error_uri = cause.error_uri;\n    }\n    return new PmtHouseError(description, {\n      status: error.status,\n      code: error.error,\n      details,\n    });\n  }\n\n  if (error instanceof OperationProcessingError) {\n    return new PmtHouseError(error.message, {\n      status: 502,\n      code: error.code ?? \"oauth_processing_error\",\n      details: { cause: error.cause },\n    });\n  }\n\n  if (error instanceof Error) {\n    return new PmtHouseError(error.message, {\n      status: 500,\n      code: \"unexpected_error\",\n    });\n  }\n\n  return new PmtHouseError(\"Unexpected error\", {\n    status: 500,\n    code: \"unexpected_error\",\n  });\n}\n\nexport function tokenEndpointResponseToExchange(\n  tr: import(\"oauth4webapi\").TokenEndpointResponse,\n): TokenExchangeResponse {\n  const issued = tr.issued_token_type;\n  if (typeof issued !== \"string\" || !ACCEPTED_ISSUED_TOKEN_TYPES.has(issued)) {\n    throw new PmtHouseError(\"Token exchange returned an unexpected issued_token_type\", {\n      status: 502,\n      code: \"invalid_token_response\",\n      details: { issued_token_type: issued },\n    });\n  }\n\n  const tt = tr.token_type;\n  if (typeof tt !== \"string\" || tt.toLowerCase() !== \"bearer\") {\n    throw new PmtHouseError(\"Token endpoint returned a non-Bearer token_type\", {\n      status: 502,\n      code: \"invalid_token_response\",\n      details: { token_type: tt },\n    });\n  }\n\n  const expiresIn = tr.expires_in;\n  if (typeof expiresIn !== \"number\") {\n    throw new PmtHouseError(\"Token response missing expires_in\", {\n      status: 502,\n      code: \"invalid_token_response\",\n    });\n  }\n\n  const scope = typeof tr.scope === \"string\" ? tr.scope : \"\";\n\n  return {\n    access_token: tr.access_token,\n    token_type: \"Bearer\",\n    expires_in: expiresIn,\n    scope,\n    issued_token_type: issued,\n  };\n}\n\nexport function tokenEndpointResponseToClientCredentials(\n  tr: import(\"oauth4webapi\").TokenEndpointResponse,\n): ClientCredentialsTokenResponse {\n  const tt = tr.token_type;\n  if (typeof tt !== \"string\" || tt.toLowerCase() !== \"bearer\") {\n    throw new PmtHouseError(\"Token endpoint returned a non-Bearer token_type\", {\n      status: 502,\n      code: \"invalid_token_response\",\n      details: { token_type: tt },\n    });\n  }\n\n  return {\n    access_token: tr.access_token,\n    token_type: \"Bearer\",\n    expires_in: tr.expires_in,\n    scope: typeof tr.scope === \"string\" ? tr.scope : undefined,\n  };\n}\n\nexport function m2mClient(clientId: string): Client {\n  return { client_id: clientId };\n}\n","import {\n  allowInsecureRequests,\n  customFetch,\n  deviceAuthorizationRequest,\n  deviceCodeGrantRequest,\n  None,\n  processDeviceAuthorizationResponse,\n  processDeviceCodeResponse,\n  ResponseBodyError,\n  type Client,\n} from \"oauth4webapi\";\nimport { loadAuthorizationServer } from \"./discovery.js\";\nimport { PmtHouseError } from \"./errors.js\";\nimport { mapOAuthError } from \"./oauth-map.js\";\nimport type { FetchLike } from \"./types.js\";\n\nexport interface PollDeviceTokenOptions {\n  issuerUrl: string;\n  /** Public OAuth `client_id` (RFC 8628). */\n  clientId: string;\n  /** Space-separated scopes for the device authorization request. */\n  scope?: string;\n  fetch?: FetchLike;\n  allowInsecureHttp?: boolean;\n  signal?: AbortSignal;\n  onUserCode?: (info: {\n    userCode: string;\n    verificationUri: string;\n    verificationUriComplete?: string;\n    expiresIn: number;\n    intervalSeconds?: number;\n  }) => void;\n}\n\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    const t = setTimeout(resolve, ms);\n    signal?.addEventListener(\n      \"abort\",\n      () => {\n        clearTimeout(t);\n        reject(\n          signal.reason instanceof Error\n            ? signal.reason\n            : new Error(typeof signal.reason === \"string\" ? signal.reason : \"Aborted\"),\n        );\n      },\n      { once: true },\n    );\n  });\n}\n\n/**\n * RFC 8628 device authorization grant: request a device code, then poll the token endpoint until\n * tokens are issued (handles `authorization_pending` and `slow_down`).\n */\nexport async function pollDeviceToken(\n  options: PollDeviceTokenOptions,\n): Promise<import(\"oauth4webapi\").TokenEndpointResponse> {\n  const fetchImpl = options.fetch ?? fetch;\n  const as = await loadAuthorizationServer(options.issuerUrl, fetchImpl, {\n    allowInsecureHttp: options.allowInsecureHttp,\n  });\n\n  if (!as.device_authorization_endpoint) {\n    throw new PmtHouseError(\n      \"Authorization server metadata has no device_authorization_endpoint\",\n      { status: 400, code: \"unsupported_grant\" },\n    );\n  }\n\n  const client: Client = { client_id: options.clientId };\n  const params = new URLSearchParams();\n  if (options.scope) {\n    params.set(\"scope\", options.scope);\n  }\n\n  const httpOpts: Record<symbol, unknown> = {\n    [customFetch]: fetchImpl,\n  };\n  if (options.allowInsecureHttp) {\n    httpOpts[allowInsecureRequests] = true;\n  }\n\n  let deviceResponse: Response;\n  try {\n    deviceResponse = await deviceAuthorizationRequest(\n      as,\n      client,\n      None(),\n      params,\n      httpOpts as import(\"oauth4webapi\").DeviceAuthorizationRequestOptions,\n    );\n  } catch (e) {\n    throw mapOAuthError(e);\n  }\n\n  let dar: import(\"oauth4webapi\").DeviceAuthorizationResponse;\n  try {\n    dar = await processDeviceAuthorizationResponse(as, client, deviceResponse);\n  } catch (e) {\n    throw mapOAuthError(e);\n  }\n\n  options.onUserCode?.({\n    userCode: dar.user_code,\n    verificationUri: dar.verification_uri,\n    verificationUriComplete: dar.verification_uri_complete,\n    expiresIn: dar.expires_in,\n    intervalSeconds: dar.interval,\n  });\n\n  let pollIntervalMs = (dar.interval ?? 5) * 1000;\n  const deadline = Date.now() + dar.expires_in * 1000;\n  let firstPoll = true;\n\n  while (Date.now() < deadline) {\n    if (options.signal?.aborted) {\n      throw options.signal.reason instanceof Error\n        ? options.signal.reason\n        : new Error(\"Aborted\");\n    }\n\n    if (!firstPoll) {\n      await sleep(pollIntervalMs, options.signal);\n    }\n    firstPoll = false;\n\n    let tokenResponse: Response;\n    try {\n      tokenResponse = await deviceCodeGrantRequest(\n        as,\n        client,\n        None(),\n        dar.device_code,\n        httpOpts as import(\"oauth4webapi\").TokenEndpointRequestOptions,\n      );\n    } catch (e) {\n      throw mapOAuthError(e);\n    }\n\n    try {\n      return await processDeviceCodeResponse(as, client, tokenResponse);\n    } catch (e) {\n      if (e instanceof ResponseBodyError) {\n        if (e.error === \"authorization_pending\") {\n          continue;\n        }\n        if (e.error === \"slow_down\") {\n          pollIntervalMs += 5000;\n          continue;\n        }\n      }\n      throw mapOAuthError(e);\n    }\n  }\n\n  throw new PmtHouseError(\"Device authorization expired before completion\", {\n    status: 408,\n    code: \"device_flow_expired\",\n  });\n}\n"]}

package/dist/device.d.cts

@@ -0,0 +1,27 @@
+import * as oauth4webapi from 'oauth4webapi';
+import { F as FetchLike } from './types-W9PJAspR.cjs';
+
+interface PollDeviceTokenOptions {
+    issuerUrl: string;
+    /** Public OAuth `client_id` (RFC 8628). */
+    clientId: string;
+    /** Space-separated scopes for the device authorization request. */
+    scope?: string;
+    fetch?: FetchLike;
+    allowInsecureHttp?: boolean;
+    signal?: AbortSignal;
+    onUserCode?: (info: {
+        userCode: string;
+        verificationUri: string;
+        verificationUriComplete?: string;
+        expiresIn: number;
+        intervalSeconds?: number;
+    }) => void;
+}
+/**
+ * RFC 8628 device authorization grant: request a device code, then poll the token endpoint until
+ * tokens are issued (handles `authorization_pending` and `slow_down`).
+ */
+declare function pollDeviceToken(options: PollDeviceTokenOptions): Promise<oauth4webapi.TokenEndpointResponse>;
+
+export { type PollDeviceTokenOptions, pollDeviceToken };

package/dist/device.d.ts

@@ -0,0 +1,27 @@
+import * as oauth4webapi from 'oauth4webapi';
+import { F as FetchLike } from './types-W9PJAspR.js';
+
+interface PollDeviceTokenOptions {
+    issuerUrl: string;
+    /** Public OAuth `client_id` (RFC 8628). */
+    clientId: string;
+    /** Space-separated scopes for the device authorization request. */
+    scope?: string;
+    fetch?: FetchLike;
+    allowInsecureHttp?: boolean;
+    signal?: AbortSignal;
+    onUserCode?: (info: {
+        userCode: string;
+        verificationUri: string;
+        verificationUriComplete?: string;
+        expiresIn: number;
+        intervalSeconds?: number;
+    }) => void;
+}
+/**
+ * RFC 8628 device authorization grant: request a device code, then poll the token endpoint until
+ * tokens are issued (handles `authorization_pending` and `slow_down`).
+ */
+declare function pollDeviceToken(options: PollDeviceTokenOptions): Promise<oauth4webapi.TokenEndpointResponse>;
+
+export { type PollDeviceTokenOptions, pollDeviceToken };