@pymthouse/builder-sdk 0.0.8 → 0.1.0

package/README.md

@@ -66,14 +66,52 @@ const signerSession = await client.mintUserSignerSessionToken({
 For advanced flows that already have a user JWT, call
 `exchangeForSignerSession({ userJwt })` directly.
 
+Integrators can use the higher-level workflow helpers:
+
+```ts
+const session = await client.mintSignerSessionForExternalUser({
+  externalUserId: "naap-user-123",
+  email: "user@example.com",
+});
+// session.accessToken is opaque pmth_…
+
+await client.approveDeviceLogin({
+  externalUserId: "naap-user-123",
+  userCode: "ABCD-EFGH",
+  publicClientId: process.env.PYMTHOUSE_PUBLIC_CLIENT_ID,
+});
+```
+
+## Usage API: session-scoped `scope=me` BFF helper
+
+```ts
+const payload = await client.fetchUsageForExternalUser({
+  externalUserId: "naap-user-123",
+  startDate,
+  endDate,
+});
+// payload.currentUser includes fiat totals + merged pipelineModels
+```
+
+## App manifest
+
+```ts
+const { manifest, etag, notModified } = await client.getAppManifest({
+  ifNoneMatch: cachedEtag ?? undefined,
+});
+```
+
 ## Subpath exports
 
 | Import | Purpose |
 |--------|---------|
-| `@pymthouse/builder-sdk` | `PmtHouseClient`, discovery cache, errors, usage aggregation helpers |
+| `@pymthouse/builder-sdk` | `PmtHouseClient`, usage helpers, manifest parsers, token helpers |
+| `@pymthouse/builder-sdk/config` | `isPymthouseConfigured`, `readPymthouseEnv` (Edge/middleware-safe) |
+| `@pymthouse/builder-sdk/tokens` | Signer session TTL, JWT shape helpers, `parseSignerSessionExchange` |
 | `@pymthouse/builder-sdk/format` | Wei formatting for Usage API |
-| `@pymthouse/builder-sdk/env` | `createPmtHouseClientFromEnv`, `getPymthouseBaseUrl` |
+| `@pymthouse/builder-sdk/env` | `createPmtHouseClientFromEnv`, `getPymthouseBaseUrl` (server-only) |
 | `@pymthouse/builder-sdk/device` | RFC 8628 `pollDeviceToken` |
+| `@pymthouse/builder-sdk/device-initiate` | Option B device login validation (Edge-safe) |
 | `@pymthouse/builder-sdk/verify` | RFC 9068 `verifyJwt` |
 
 ## Usage API: duplicate `byUser` rows

package/dist/{env-CZczUMzR.d.cts → client-BhC1YhB1.d.cts}

@@ -1,4 +1,5 @@
-import { f as PmtHouseClientOptions, G as GetDiscoveryOptions, O as OidcDiscoveryDocument, P as ParsedDeviceApprovalRedirect, A as AppUserRecord, g as UpsertAppUserInput, M as MintUserAccessTokenInput, d as MintUserAccessTokenResponse, D as DeviceApprovalInput, T as TokenExchangeResponse, C as ClientCredentialsTokenResponse, e as MintUserSignerSessionTokenInput, h as UsageQueryInput, b as UsageApiResponse } from './types-W9PJAspR.cjs';
+import { SignerSessionToken } from './tokens.cjs';
+import { m as PmtHouseClientOptions, h as GetDiscoveryOptions, O as OidcDiscoveryDocument, P as ParsedDeviceApprovalRedirect, f as AppUserRecord, n as UpsertAppUserInput, j as MintUserAccessTokenInput, k as MintUserAccessTokenResponse, D as DeviceApprovalInput, T as TokenExchangeResponse, C as ClientCredentialsTokenResponse, l as MintUserSignerSessionTokenInput, o as UsageQueryInput, b as UsageApiResponse, M as MeScopeUsagePayload, G as GetAppManifestResult, i as MintSignerSessionForExternalUserInput, g as ApproveDeviceLoginInput } from './types-rKzVXvMu.cjs';
 
 /**
  * Normalize RFC 8628 user codes for comparison and resource URIs (uppercase, strip separators).
@@ -45,24 +46,36 @@ declare class PmtHouseClient {
         userJwt?: string;
     }): Promise<TokenExchangeResponse>;
     getUsage(input?: UsageQueryInput): Promise<UsageApiResponse>;
+    /**
+     * Session-scoped usage for one `externalUserId`: user rollup plus merged pipeline/model breakdown.
+     */
+    fetchUsageForExternalUser(input: {
+        externalUserId: string;
+        startDate: string;
+        endDate: string;
+        maxEndUserIds?: number;
+    }): Promise<MeScopeUsagePayload>;
+    getAppManifest(opts?: {
+        ifNoneMatch?: string;
+        signal?: AbortSignal;
+    }): Promise<GetAppManifestResult>;
+    /**
+     * Upsert an external user, mint a short-lived JWT, and exchange for an opaque signer session.
+     */
+    mintSignerSessionForExternalUser(input: MintSignerSessionForExternalUserInput): Promise<SignerSessionToken>;
+    /**
+     * Approve a pending RFC 8628 device code for an external user (Option B).
+     */
+    approveDeviceLogin(input: ApproveDeviceLoginInput): Promise<void>;
     private tokenEndpointFetchOptions;
     private getAppsBaseUrl;
     private getIssuerOrigin;
     private builderHeaders;
+    private builderHeadersRecord;
     private m2mClientAuth;
     private requestJson;
     private safeParseJson;
     private asError;
 }
 
-/**
- * Site origin for the PymtHouse deployment (e.g. https://pymthouse.com), derived
- * from `PYMTHOUSE_ISSUER_URL`.
- */
-declare function getPymthouseBaseUrl(): string;
-/**
- * Singleton `PmtHouseClient` from `PYMTHOUSE_*` environment variables (server-side).
- */
-declare function createPmtHouseClientFromEnv(): PmtHouseClient;
-
-export { PmtHouseClient as P, buildDeviceCodeResource as b, createPmtHouseClientFromEnv as c, getPymthouseBaseUrl as g, normalizeUserCode as n };
+export { PmtHouseClient as P, buildDeviceCodeResource as b, normalizeUserCode as n };

package/dist/{env-4YmzarGJ.d.ts → client-BroVFyIy.d.ts}

@@ -1,4 +1,5 @@
-import { f as PmtHouseClientOptions, G as GetDiscoveryOptions, O as OidcDiscoveryDocument, P as ParsedDeviceApprovalRedirect, A as AppUserRecord, g as UpsertAppUserInput, M as MintUserAccessTokenInput, d as MintUserAccessTokenResponse, D as DeviceApprovalInput, T as TokenExchangeResponse, C as ClientCredentialsTokenResponse, e as MintUserSignerSessionTokenInput, h as UsageQueryInput, b as UsageApiResponse } from './types-W9PJAspR.js';
+import { SignerSessionToken } from './tokens.js';
+import { m as PmtHouseClientOptions, h as GetDiscoveryOptions, O as OidcDiscoveryDocument, P as ParsedDeviceApprovalRedirect, f as AppUserRecord, n as UpsertAppUserInput, j as MintUserAccessTokenInput, k as MintUserAccessTokenResponse, D as DeviceApprovalInput, T as TokenExchangeResponse, C as ClientCredentialsTokenResponse, l as MintUserSignerSessionTokenInput, o as UsageQueryInput, b as UsageApiResponse, M as MeScopeUsagePayload, G as GetAppManifestResult, i as MintSignerSessionForExternalUserInput, g as ApproveDeviceLoginInput } from './types-rKzVXvMu.js';
 
 /**
  * Normalize RFC 8628 user codes for comparison and resource URIs (uppercase, strip separators).
@@ -45,24 +46,36 @@ declare class PmtHouseClient {
         userJwt?: string;
     }): Promise<TokenExchangeResponse>;
     getUsage(input?: UsageQueryInput): Promise<UsageApiResponse>;
+    /**
+     * Session-scoped usage for one `externalUserId`: user rollup plus merged pipeline/model breakdown.
+     */
+    fetchUsageForExternalUser(input: {
+        externalUserId: string;
+        startDate: string;
+        endDate: string;
+        maxEndUserIds?: number;
+    }): Promise<MeScopeUsagePayload>;
+    getAppManifest(opts?: {
+        ifNoneMatch?: string;
+        signal?: AbortSignal;
+    }): Promise<GetAppManifestResult>;
+    /**
+     * Upsert an external user, mint a short-lived JWT, and exchange for an opaque signer session.
+     */
+    mintSignerSessionForExternalUser(input: MintSignerSessionForExternalUserInput): Promise<SignerSessionToken>;
+    /**
+     * Approve a pending RFC 8628 device code for an external user (Option B).
+     */
+    approveDeviceLogin(input: ApproveDeviceLoginInput): Promise<void>;
     private tokenEndpointFetchOptions;
     private getAppsBaseUrl;
     private getIssuerOrigin;
     private builderHeaders;
+    private builderHeadersRecord;
     private m2mClientAuth;
     private requestJson;
     private safeParseJson;
     private asError;
 }
 
-/**
- * Site origin for the PymtHouse deployment (e.g. https://pymthouse.com), derived
- * from `PYMTHOUSE_ISSUER_URL`.
- */
-declare function getPymthouseBaseUrl(): string;
-/**
- * Singleton `PmtHouseClient` from `PYMTHOUSE_*` environment variables (server-side).
- */
-declare function createPmtHouseClientFromEnv(): PmtHouseClient;
-
-export { PmtHouseClient as P, buildDeviceCodeResource as b, createPmtHouseClientFromEnv as c, getPymthouseBaseUrl as g, normalizeUserCode as n };
+export { PmtHouseClient as P, buildDeviceCodeResource as b, normalizeUserCode as n };

package/dist/config.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+// 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/config.ts
+var PYMTHOUSE_NOT_CONFIGURED_MESSAGE = "PymtHouse is not configured. Set PYMTHOUSE_ISSUER_URL, PYMTHOUSE_PUBLIC_CLIENT_ID, PYMTHOUSE_M2M_CLIENT_ID, and PYMTHOUSE_M2M_CLIENT_SECRET, then restart.";
+function trimEnv(name) {
+  const value = process.env[name];
+  if (!value) return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+function readPymthouseEnv() {
+  const issuerUrl = trimEnv("PYMTHOUSE_ISSUER_URL");
+  const publicClientId = trimEnv("PYMTHOUSE_PUBLIC_CLIENT_ID");
+  const m2mClientId = trimEnv("PYMTHOUSE_M2M_CLIENT_ID");
+  const m2mClientSecret = trimEnv("PYMTHOUSE_M2M_CLIENT_SECRET");
+  if (!issuerUrl || !publicClientId || !m2mClientId || !m2mClientSecret) {
+    return null;
+  }
+  return {
+    issuerUrl: stripTrailingSlashes(issuerUrl),
+    publicClientId,
+    m2mClientId,
+    m2mClientSecret
+  };
+}
+function getPymthouseIssuerUrlFromEnv() {
+  const raw = trimEnv("PYMTHOUSE_ISSUER_URL");
+  if (!raw) return null;
+  try {
+    return stripTrailingSlashes(new URL(raw).href);
+  } catch {
+    return null;
+  }
+}
+function getPymthousePublicClientIdFromEnv() {
+  return trimEnv("PYMTHOUSE_PUBLIC_CLIENT_ID");
+}
+function isPymthouseConfigured() {
+  return readPymthouseEnv() !== null;
+}
+function getBuilderApiV1BaseFromIssuerUrl(issuerUrl) {
+  const noTrail = stripTrailingSlashes(issuerUrl.trim());
+  return noTrail.replace(/\/oidc\/?$/i, "");
+}
+function getPymthouseIssuerOrigin(issuerUrl) {
+  return new URL(stripTrailingSlashes(issuerUrl.trim())).origin;
+}
+
+exports.PYMTHOUSE_NOT_CONFIGURED_MESSAGE = PYMTHOUSE_NOT_CONFIGURED_MESSAGE;
+exports.getBuilderApiV1BaseFromIssuerUrl = getBuilderApiV1BaseFromIssuerUrl;
+exports.getPymthouseIssuerOrigin = getPymthouseIssuerOrigin;
+exports.getPymthouseIssuerUrlFromEnv = getPymthouseIssuerUrlFromEnv;
+exports.getPymthousePublicClientIdFromEnv = getPymthousePublicClientIdFromEnv;
+exports.isPymthouseConfigured = isPymthouseConfigured;
+exports.readPymthouseEnv = readPymthouseEnv;
+//# sourceMappingURL=config.cjs.map
+//# sourceMappingURL=config.cjs.map

package/dist/config.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/string-utils.ts","../src/config.ts"],"names":[],"mappings":";;;AACO,SAAS,qBAAqB,KAAA,EAAuB;AAC1D,EAAA,IAAI,MAAM,KAAA,CAAM,MAAA;AAChB,EAAA,OAAO,MAAM,CAAA,IAAK,KAAA,CAAM,WAAW,GAAA,GAAM,CAAC,MAAM,EAAA,EAAI;AAClD,IAAA,GAAA,EAAA;AAAA,EACF;AACA,EAAA,OAAO,KAAA,CAAM,KAAA,CAAM,CAAA,EAAG,GAAG,CAAA;AAC3B;;;ACJO,IAAM,gCAAA,GACX;AASF,SAAS,QAAQ,IAAA,EAA6B;AAC5C,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAA;AAC9B,EAAA,IAAI,CAAC,OAAO,OAAO,IAAA;AACnB,EAAA,MAAM,OAAA,GAAU,MAAM,IAAA,EAAK;AAC3B,EAAA,OAAO,OAAA,IAAW,IAAA;AACpB;AAGO,SAAS,gBAAA,GAA8C;AAC5D,EAAA,MAAM,SAAA,GAAY,QAAQ,sBAAsB,CAAA;AAChD,EAAA,MAAM,cAAA,GAAiB,QAAQ,4BAA4B,CAAA;AAC3D,EAAA,MAAM,WAAA,GAAc,QAAQ,yBAAyB,CAAA;AACrD,EAAA,MAAM,eAAA,GAAkB,QAAQ,6BAA6B,CAAA;AAC7D,EAAA,IAAI,CAAC,SAAA,IAAa,CAAC,kBAAkB,CAAC,WAAA,IAAe,CAAC,eAAA,EAAiB;AACrE,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,OAAO;AAAA,IACL,SAAA,EAAW,qBAAqB,SAAS,CAAA;AAAA,IACzC,cAAA;AAAA,IACA,WAAA;AAAA,IACA;AAAA,GACF;AACF;AAGO,SAAS,4BAAA,GAA8C;AAC5D,EAAA,MAAM,GAAA,GAAM,QAAQ,sBAAsB,CAAA;AAC1C,EAAA,IAAI,CAAC,KAAK,OAAO,IAAA;AACjB,EAAA,IAAI;AACF,IAAA,OAAO,oBAAA,CAAqB,IAAI,GAAA,CAAI,GAAG,EAAE,IAAI,CAAA;AAAA,EAC/C,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAGO,SAAS,iCAAA,GAAmD;AACjE,EAAA,OAAO,QAAQ,4BAA4B,CAAA;AAC7C;AAGO,SAAS,qBAAA,GAAiC;AAC/C,EAAA,OAAO,kBAAiB,KAAM,IAAA;AAChC;AAGO,SAAS,iCAAiC,SAAA,EAA2B;AAC1E,EAAA,MAAM,OAAA,GAAU,oBAAA,CAAqB,SAAA,CAAU,IAAA,EAAM,CAAA;AACrD,EAAA,OAAO,OAAA,CAAQ,OAAA,CAAQ,aAAA,EAAe,EAAE,CAAA;AAC1C;AAGO,SAAS,yBAAyB,SAAA,EAA2B;AAClE,EAAA,OAAO,IAAI,GAAA,CAAI,oBAAA,CAAqB,UAAU,IAAA,EAAM,CAAC,CAAA,CAAE,MAAA;AACzD","file":"config.cjs","sourcesContent":["/** 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 { stripTrailingSlashes } from \"./string-utils.js\";\n\n/** Operator hint when Builder / Usage cannot run. */\nexport const PYMTHOUSE_NOT_CONFIGURED_MESSAGE =\n  \"PymtHouse is not configured. Set PYMTHOUSE_ISSUER_URL, PYMTHOUSE_PUBLIC_CLIENT_ID, PYMTHOUSE_M2M_CLIENT_ID, and PYMTHOUSE_M2M_CLIENT_SECRET, then restart.\";\n\nexport interface PymthouseEnvConfig {\n  issuerUrl: string;\n  publicClientId: string;\n  m2mClientId: string;\n  m2mClientSecret: string;\n}\n\nfunction trimEnv(name: string): string | null {\n  const value = process.env[name];\n  if (!value) return null;\n  const trimmed = value.trim();\n  return trimmed || null;\n}\n\n/** Read `PYMTHOUSE_*` env vars without throwing. Returns null when incomplete. */\nexport function readPymthouseEnv(): PymthouseEnvConfig | null {\n  const issuerUrl = trimEnv(\"PYMTHOUSE_ISSUER_URL\");\n  const publicClientId = trimEnv(\"PYMTHOUSE_PUBLIC_CLIENT_ID\");\n  const m2mClientId = trimEnv(\"PYMTHOUSE_M2M_CLIENT_ID\");\n  const m2mClientSecret = trimEnv(\"PYMTHOUSE_M2M_CLIENT_SECRET\");\n  if (!issuerUrl || !publicClientId || !m2mClientId || !m2mClientSecret) {\n    return null;\n  }\n  return {\n    issuerUrl: stripTrailingSlashes(issuerUrl),\n    publicClientId,\n    m2mClientId,\n    m2mClientSecret,\n  };\n}\n\n/** Read `PYMTHOUSE_ISSUER_URL` without requiring full M2M configuration. */\nexport function getPymthouseIssuerUrlFromEnv(): string | null {\n  const raw = trimEnv(\"PYMTHOUSE_ISSUER_URL\");\n  if (!raw) return null;\n  try {\n    return stripTrailingSlashes(new URL(raw).href);\n  } catch {\n    return null;\n  }\n}\n\n/** Read `PYMTHOUSE_PUBLIC_CLIENT_ID` without requiring full M2M configuration. */\nexport function getPymthousePublicClientIdFromEnv(): string | null {\n  return trimEnv(\"PYMTHOUSE_PUBLIC_CLIENT_ID\");\n}\n\n/** True when all vars required by `createPmtHouseClientFromEnv` are present. */\nexport function isPymthouseConfigured(): boolean {\n  return readPymthouseEnv() !== null;\n}\n\n/** Resolve Builder API base (`…/api/v1`) from issuer URL (`…/api/v1/oidc`). */\nexport function getBuilderApiV1BaseFromIssuerUrl(issuerUrl: string): string {\n  const noTrail = stripTrailingSlashes(issuerUrl.trim());\n  return noTrail.replace(/\\/oidc\\/?$/i, \"\");\n}\n\n/** Origin of the OIDC issuer host (e.g. `https://pymthouse.com`). */\nexport function getPymthouseIssuerOrigin(issuerUrl: string): string {\n  return new URL(stripTrailingSlashes(issuerUrl.trim())).origin;\n}\n"]}

package/dist/config.d.cts

@@ -0,0 +1,22 @@
+/** Operator hint when Builder / Usage cannot run. */
+declare const PYMTHOUSE_NOT_CONFIGURED_MESSAGE = "PymtHouse is not configured. Set PYMTHOUSE_ISSUER_URL, PYMTHOUSE_PUBLIC_CLIENT_ID, PYMTHOUSE_M2M_CLIENT_ID, and PYMTHOUSE_M2M_CLIENT_SECRET, then restart.";
+interface PymthouseEnvConfig {
+    issuerUrl: string;
+    publicClientId: string;
+    m2mClientId: string;
+    m2mClientSecret: string;
+}
+/** Read `PYMTHOUSE_*` env vars without throwing. Returns null when incomplete. */
+declare function readPymthouseEnv(): PymthouseEnvConfig | null;
+/** Read `PYMTHOUSE_ISSUER_URL` without requiring full M2M configuration. */
+declare function getPymthouseIssuerUrlFromEnv(): string | null;
+/** Read `PYMTHOUSE_PUBLIC_CLIENT_ID` without requiring full M2M configuration. */
+declare function getPymthousePublicClientIdFromEnv(): string | null;
+/** True when all vars required by `createPmtHouseClientFromEnv` are present. */
+declare function isPymthouseConfigured(): boolean;
+/** Resolve Builder API base (`…/api/v1`) from issuer URL (`…/api/v1/oidc`). */
+declare function getBuilderApiV1BaseFromIssuerUrl(issuerUrl: string): string;
+/** Origin of the OIDC issuer host (e.g. `https://pymthouse.com`). */
+declare function getPymthouseIssuerOrigin(issuerUrl: string): string;
+
+export { PYMTHOUSE_NOT_CONFIGURED_MESSAGE, type PymthouseEnvConfig, getBuilderApiV1BaseFromIssuerUrl, getPymthouseIssuerOrigin, getPymthouseIssuerUrlFromEnv, getPymthousePublicClientIdFromEnv, isPymthouseConfigured, readPymthouseEnv };

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+/** Operator hint when Builder / Usage cannot run. */
+declare const PYMTHOUSE_NOT_CONFIGURED_MESSAGE = "PymtHouse is not configured. Set PYMTHOUSE_ISSUER_URL, PYMTHOUSE_PUBLIC_CLIENT_ID, PYMTHOUSE_M2M_CLIENT_ID, and PYMTHOUSE_M2M_CLIENT_SECRET, then restart.";
+interface PymthouseEnvConfig {
+    issuerUrl: string;
+    publicClientId: string;
+    m2mClientId: string;
+    m2mClientSecret: string;
+}
+/** Read `PYMTHOUSE_*` env vars without throwing. Returns null when incomplete. */
+declare function readPymthouseEnv(): PymthouseEnvConfig | null;
+/** Read `PYMTHOUSE_ISSUER_URL` without requiring full M2M configuration. */
+declare function getPymthouseIssuerUrlFromEnv(): string | null;
+/** Read `PYMTHOUSE_PUBLIC_CLIENT_ID` without requiring full M2M configuration. */
+declare function getPymthousePublicClientIdFromEnv(): string | null;
+/** True when all vars required by `createPmtHouseClientFromEnv` are present. */
+declare function isPymthouseConfigured(): boolean;
+/** Resolve Builder API base (`…/api/v1`) from issuer URL (`…/api/v1/oidc`). */
+declare function getBuilderApiV1BaseFromIssuerUrl(issuerUrl: string): string;
+/** Origin of the OIDC issuer host (e.g. `https://pymthouse.com`). */
+declare function getPymthouseIssuerOrigin(issuerUrl: string): string;
+
+export { PYMTHOUSE_NOT_CONFIGURED_MESSAGE, type PymthouseEnvConfig, getBuilderApiV1BaseFromIssuerUrl, getPymthouseIssuerOrigin, getPymthouseIssuerUrlFromEnv, getPymthousePublicClientIdFromEnv, isPymthouseConfigured, readPymthouseEnv };

package/dist/config.js

@@ -0,0 +1,58 @@
+// 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/config.ts
+var PYMTHOUSE_NOT_CONFIGURED_MESSAGE = "PymtHouse is not configured. Set PYMTHOUSE_ISSUER_URL, PYMTHOUSE_PUBLIC_CLIENT_ID, PYMTHOUSE_M2M_CLIENT_ID, and PYMTHOUSE_M2M_CLIENT_SECRET, then restart.";
+function trimEnv(name) {
+  const value = process.env[name];
+  if (!value) return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+function readPymthouseEnv() {
+  const issuerUrl = trimEnv("PYMTHOUSE_ISSUER_URL");
+  const publicClientId = trimEnv("PYMTHOUSE_PUBLIC_CLIENT_ID");
+  const m2mClientId = trimEnv("PYMTHOUSE_M2M_CLIENT_ID");
+  const m2mClientSecret = trimEnv("PYMTHOUSE_M2M_CLIENT_SECRET");
+  if (!issuerUrl || !publicClientId || !m2mClientId || !m2mClientSecret) {
+    return null;
+  }
+  return {
+    issuerUrl: stripTrailingSlashes(issuerUrl),
+    publicClientId,
+    m2mClientId,
+    m2mClientSecret
+  };
+}
+function getPymthouseIssuerUrlFromEnv() {
+  const raw = trimEnv("PYMTHOUSE_ISSUER_URL");
+  if (!raw) return null;
+  try {
+    return stripTrailingSlashes(new URL(raw).href);
+  } catch {
+    return null;
+  }
+}
+function getPymthousePublicClientIdFromEnv() {
+  return trimEnv("PYMTHOUSE_PUBLIC_CLIENT_ID");
+}
+function isPymthouseConfigured() {
+  return readPymthouseEnv() !== null;
+}
+function getBuilderApiV1BaseFromIssuerUrl(issuerUrl) {
+  const noTrail = stripTrailingSlashes(issuerUrl.trim());
+  return noTrail.replace(/\/oidc\/?$/i, "");
+}
+function getPymthouseIssuerOrigin(issuerUrl) {
+  return new URL(stripTrailingSlashes(issuerUrl.trim())).origin;
+}
+
+export { PYMTHOUSE_NOT_CONFIGURED_MESSAGE, getBuilderApiV1BaseFromIssuerUrl, getPymthouseIssuerOrigin, getPymthouseIssuerUrlFromEnv, getPymthousePublicClientIdFromEnv, isPymthouseConfigured, readPymthouseEnv };
+//# sourceMappingURL=config.js.map
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/string-utils.ts","../src/config.ts"],"names":[],"mappings":";AACO,SAAS,qBAAqB,KAAA,EAAuB;AAC1D,EAAA,IAAI,MAAM,KAAA,CAAM,MAAA;AAChB,EAAA,OAAO,MAAM,CAAA,IAAK,KAAA,CAAM,WAAW,GAAA,GAAM,CAAC,MAAM,EAAA,EAAI;AAClD,IAAA,GAAA,EAAA;AAAA,EACF;AACA,EAAA,OAAO,KAAA,CAAM,KAAA,CAAM,CAAA,EAAG,GAAG,CAAA;AAC3B;;;ACJO,IAAM,gCAAA,GACX;AASF,SAAS,QAAQ,IAAA,EAA6B;AAC5C,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAA;AAC9B,EAAA,IAAI,CAAC,OAAO,OAAO,IAAA;AACnB,EAAA,MAAM,OAAA,GAAU,MAAM,IAAA,EAAK;AAC3B,EAAA,OAAO,OAAA,IAAW,IAAA;AACpB;AAGO,SAAS,gBAAA,GAA8C;AAC5D,EAAA,MAAM,SAAA,GAAY,QAAQ,sBAAsB,CAAA;AAChD,EAAA,MAAM,cAAA,GAAiB,QAAQ,4BAA4B,CAAA;AAC3D,EAAA,MAAM,WAAA,GAAc,QAAQ,yBAAyB,CAAA;AACrD,EAAA,MAAM,eAAA,GAAkB,QAAQ,6BAA6B,CAAA;AAC7D,EAAA,IAAI,CAAC,SAAA,IAAa,CAAC,kBAAkB,CAAC,WAAA,IAAe,CAAC,eAAA,EAAiB;AACrE,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,OAAO;AAAA,IACL,SAAA,EAAW,qBAAqB,SAAS,CAAA;AAAA,IACzC,cAAA;AAAA,IACA,WAAA;AAAA,IACA;AAAA,GACF;AACF;AAGO,SAAS,4BAAA,GAA8C;AAC5D,EAAA,MAAM,GAAA,GAAM,QAAQ,sBAAsB,CAAA;AAC1C,EAAA,IAAI,CAAC,KAAK,OAAO,IAAA;AACjB,EAAA,IAAI;AACF,IAAA,OAAO,oBAAA,CAAqB,IAAI,GAAA,CAAI,GAAG,EAAE,IAAI,CAAA;AAAA,EAC/C,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAGO,SAAS,iCAAA,GAAmD;AACjE,EAAA,OAAO,QAAQ,4BAA4B,CAAA;AAC7C;AAGO,SAAS,qBAAA,GAAiC;AAC/C,EAAA,OAAO,kBAAiB,KAAM,IAAA;AAChC;AAGO,SAAS,iCAAiC,SAAA,EAA2B;AAC1E,EAAA,MAAM,OAAA,GAAU,oBAAA,CAAqB,SAAA,CAAU,IAAA,EAAM,CAAA;AACrD,EAAA,OAAO,OAAA,CAAQ,OAAA,CAAQ,aAAA,EAAe,EAAE,CAAA;AAC1C;AAGO,SAAS,yBAAyB,SAAA,EAA2B;AAClE,EAAA,OAAO,IAAI,GAAA,CAAI,oBAAA,CAAqB,UAAU,IAAA,EAAM,CAAC,CAAA,CAAE,MAAA;AACzD","file":"config.js","sourcesContent":["/** 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 { stripTrailingSlashes } from \"./string-utils.js\";\n\n/** Operator hint when Builder / Usage cannot run. */\nexport const PYMTHOUSE_NOT_CONFIGURED_MESSAGE =\n  \"PymtHouse is not configured. Set PYMTHOUSE_ISSUER_URL, PYMTHOUSE_PUBLIC_CLIENT_ID, PYMTHOUSE_M2M_CLIENT_ID, and PYMTHOUSE_M2M_CLIENT_SECRET, then restart.\";\n\nexport interface PymthouseEnvConfig {\n  issuerUrl: string;\n  publicClientId: string;\n  m2mClientId: string;\n  m2mClientSecret: string;\n}\n\nfunction trimEnv(name: string): string | null {\n  const value = process.env[name];\n  if (!value) return null;\n  const trimmed = value.trim();\n  return trimmed || null;\n}\n\n/** Read `PYMTHOUSE_*` env vars without throwing. Returns null when incomplete. */\nexport function readPymthouseEnv(): PymthouseEnvConfig | null {\n  const issuerUrl = trimEnv(\"PYMTHOUSE_ISSUER_URL\");\n  const publicClientId = trimEnv(\"PYMTHOUSE_PUBLIC_CLIENT_ID\");\n  const m2mClientId = trimEnv(\"PYMTHOUSE_M2M_CLIENT_ID\");\n  const m2mClientSecret = trimEnv(\"PYMTHOUSE_M2M_CLIENT_SECRET\");\n  if (!issuerUrl || !publicClientId || !m2mClientId || !m2mClientSecret) {\n    return null;\n  }\n  return {\n    issuerUrl: stripTrailingSlashes(issuerUrl),\n    publicClientId,\n    m2mClientId,\n    m2mClientSecret,\n  };\n}\n\n/** Read `PYMTHOUSE_ISSUER_URL` without requiring full M2M configuration. */\nexport function getPymthouseIssuerUrlFromEnv(): string | null {\n  const raw = trimEnv(\"PYMTHOUSE_ISSUER_URL\");\n  if (!raw) return null;\n  try {\n    return stripTrailingSlashes(new URL(raw).href);\n  } catch {\n    return null;\n  }\n}\n\n/** Read `PYMTHOUSE_PUBLIC_CLIENT_ID` without requiring full M2M configuration. */\nexport function getPymthousePublicClientIdFromEnv(): string | null {\n  return trimEnv(\"PYMTHOUSE_PUBLIC_CLIENT_ID\");\n}\n\n/** True when all vars required by `createPmtHouseClientFromEnv` are present. */\nexport function isPymthouseConfigured(): boolean {\n  return readPymthouseEnv() !== null;\n}\n\n/** Resolve Builder API base (`…/api/v1`) from issuer URL (`…/api/v1/oidc`). */\nexport function getBuilderApiV1BaseFromIssuerUrl(issuerUrl: string): string {\n  const noTrail = stripTrailingSlashes(issuerUrl.trim());\n  return noTrail.replace(/\\/oidc\\/?$/i, \"\");\n}\n\n/** Origin of the OIDC issuer host (e.g. `https://pymthouse.com`). */\nexport function getPymthouseIssuerOrigin(issuerUrl: string): string {\n  return new URL(stripTrailingSlashes(issuerUrl.trim())).origin;\n}\n"]}

package/dist/device-initiate.cjs

@@ -0,0 +1,88 @@
+'use strict';
+
+// 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/device-initiate.ts
+var USER_CODE_RE = /^(?=.*[A-Z0-9])[A-Z0-9-]{4,16}$/;
+function normalizeIssuerUrl(iss) {
+  try {
+    return stripTrailingSlashes(new URL(iss.trim()).href);
+  } catch {
+    return iss.trim();
+  }
+}
+function validateDeviceInitiateLogin(input) {
+  const expectedIss = stripTrailingSlashes(input.expectedIssuerUrl.trim());
+  let opOrigin;
+  try {
+    opOrigin = new URL(expectedIss).origin;
+  } catch {
+    return { ok: false, reason: "server_not_configured" };
+  }
+  if (normalizeIssuerUrl(input.iss) !== normalizeIssuerUrl(expectedIss)) {
+    return { ok: false, reason: "iss_mismatch" };
+  }
+  let target;
+  try {
+    target = new URL(input.targetLinkUri);
+  } catch {
+    return { ok: false, reason: "bad_target_uri" };
+  }
+  if (target.origin !== opOrigin) {
+    return { ok: false, reason: "target_origin_mismatch" };
+  }
+  if (target.pathname !== "/oidc/device") {
+    return { ok: false, reason: "target_path_mismatch" };
+  }
+  if (target.hash) {
+    return { ok: false, reason: "target_has_hash" };
+  }
+  return { ok: true, returnUrl: target.href };
+}
+function extractDeviceApprovalFromTargetLink(targetHref, opts) {
+  let target;
+  try {
+    target = new URL(targetHref);
+  } catch {
+    return { error: "bad_target_uri" };
+  }
+  if (opts?.expectedIssuerUrl) {
+    let opOrigin;
+    try {
+      opOrigin = new URL(stripTrailingSlashes(opts.expectedIssuerUrl.trim())).origin;
+    } catch {
+      return { error: "target_origin_mismatch" };
+    }
+    if (target.origin !== opOrigin) {
+      return { error: "target_origin_mismatch" };
+    }
+  }
+  if (target.pathname !== "/oidc/device") {
+    return { error: "target_path_mismatch" };
+  }
+  const userCodeRaw = target.searchParams.get("user_code")?.trim() ?? "";
+  const clientIdRaw = target.searchParams.get("client_id")?.trim() ?? "";
+  if (!userCodeRaw || !USER_CODE_RE.test(userCodeRaw)) {
+    return { error: "invalid_user_code" };
+  }
+  if (!clientIdRaw?.startsWith("app_")) {
+    return { error: "invalid_client_id" };
+  }
+  if (opts?.expectedPublicClientId && clientIdRaw !== opts.expectedPublicClientId) {
+    return { error: "client_id_mismatch" };
+  }
+  return { userCode: userCodeRaw, publicClientId: clientIdRaw };
+}
+
+exports.USER_CODE_RE = USER_CODE_RE;
+exports.extractDeviceApprovalFromTargetLink = extractDeviceApprovalFromTargetLink;
+exports.validateDeviceInitiateLogin = validateDeviceInitiateLogin;
+//# sourceMappingURL=device-initiate.cjs.map
+//# sourceMappingURL=device-initiate.cjs.map

package/dist/device-initiate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/string-utils.ts","../src/device-initiate.ts"],"names":[],"mappings":"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","file":"device-initiate.cjs","sourcesContent":["/** 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 { stripTrailingSlashes } from \"./string-utils.js\";\n\n/** RFC 8628 user codes: 4–16 chars, at least one alphanumeric (not all dashes). */\nexport const USER_CODE_RE = /^(?=.*[A-Z0-9])[A-Z0-9-]{4,16}$/;\n\nexport type ValidateDeviceInitiateResult =\n  | { ok: true; returnUrl: string }\n  | { ok: false; reason: string };\n\nexport type DeviceApprovalTuple =\n  | { userCode: string; publicClientId: string }\n  | { error: string };\n\nfunction normalizeIssuerUrl(iss: string): string {\n  try {\n    return stripTrailingSlashes(new URL(iss.trim()).href);\n  } catch {\n    return iss.trim();\n  }\n}\n\n/**\n * Validate OP-issued `iss` + `target_link_uri` before storing a device approval cookie.\n */\nexport function validateDeviceInitiateLogin(input: {\n  expectedIssuerUrl: string;\n  iss: string;\n  targetLinkUri: string;\n}): ValidateDeviceInitiateResult {\n  const expectedIss = stripTrailingSlashes(input.expectedIssuerUrl.trim());\n  let opOrigin: string;\n  try {\n    opOrigin = new URL(expectedIss).origin;\n  } catch {\n    return { ok: false, reason: \"server_not_configured\" };\n  }\n\n  if (normalizeIssuerUrl(input.iss) !== normalizeIssuerUrl(expectedIss)) {\n    return { ok: false, reason: \"iss_mismatch\" };\n  }\n\n  let target: URL;\n  try {\n    target = new URL(input.targetLinkUri);\n  } catch {\n    return { ok: false, reason: \"bad_target_uri\" };\n  }\n  if (target.origin !== opOrigin) {\n    return { ok: false, reason: \"target_origin_mismatch\" };\n  }\n  if (target.pathname !== \"/oidc/device\") {\n    return { ok: false, reason: \"target_path_mismatch\" };\n  }\n  if (target.hash) {\n    return { ok: false, reason: \"target_has_hash\" };\n  }\n  return { ok: true, returnUrl: target.href };\n}\n\n/**\n * Parse PymtHouse `/oidc/device` URL query for `user_code` + `client_id`.\n */\nexport function extractDeviceApprovalFromTargetLink(\n  targetHref: string,\n  opts?: { expectedIssuerUrl?: string; expectedPublicClientId?: string },\n): DeviceApprovalTuple {\n  let target: URL;\n  try {\n    target = new URL(targetHref);\n  } catch {\n    return { error: \"bad_target_uri\" };\n  }\n\n  if (opts?.expectedIssuerUrl) {\n    let opOrigin: string;\n    try {\n      opOrigin = new URL(stripTrailingSlashes(opts.expectedIssuerUrl.trim())).origin;\n    } catch {\n      return { error: \"target_origin_mismatch\" };\n    }\n    if (target.origin !== opOrigin) {\n      return { error: \"target_origin_mismatch\" };\n    }\n  }\n\n  if (target.pathname !== \"/oidc/device\") {\n    return { error: \"target_path_mismatch\" };\n  }\n\n  const userCodeRaw = target.searchParams.get(\"user_code\")?.trim() ?? \"\";\n  const clientIdRaw = target.searchParams.get(\"client_id\")?.trim() ?? \"\";\n  if (!userCodeRaw || !USER_CODE_RE.test(userCodeRaw)) {\n    return { error: \"invalid_user_code\" };\n  }\n  if (!clientIdRaw?.startsWith(\"app_\")) {\n    return { error: \"invalid_client_id\" };\n  }\n  if (opts?.expectedPublicClientId && clientIdRaw !== opts.expectedPublicClientId) {\n    return { error: \"client_id_mismatch\" };\n  }\n  return { userCode: userCodeRaw, publicClientId: clientIdRaw };\n}\n"]}

package/dist/device-initiate.d.cts

@@ -0,0 +1,32 @@
+/** RFC 8628 user codes: 4–16 chars, at least one alphanumeric (not all dashes). */
+declare const USER_CODE_RE: RegExp;
+type ValidateDeviceInitiateResult = {
+    ok: true;
+    returnUrl: string;
+} | {
+    ok: false;
+    reason: string;
+};
+type DeviceApprovalTuple = {
+    userCode: string;
+    publicClientId: string;
+} | {
+    error: string;
+};
+/**
+ * Validate OP-issued `iss` + `target_link_uri` before storing a device approval cookie.
+ */
+declare function validateDeviceInitiateLogin(input: {
+    expectedIssuerUrl: string;
+    iss: string;
+    targetLinkUri: string;
+}): ValidateDeviceInitiateResult;
+/**
+ * Parse PymtHouse `/oidc/device` URL query for `user_code` + `client_id`.
+ */
+declare function extractDeviceApprovalFromTargetLink(targetHref: string, opts?: {
+    expectedIssuerUrl?: string;
+    expectedPublicClientId?: string;
+}): DeviceApprovalTuple;
+
+export { type DeviceApprovalTuple, USER_CODE_RE, type ValidateDeviceInitiateResult, extractDeviceApprovalFromTargetLink, validateDeviceInitiateLogin };

package/dist/device-initiate.d.ts

@@ -0,0 +1,32 @@
+/** RFC 8628 user codes: 4–16 chars, at least one alphanumeric (not all dashes). */
+declare const USER_CODE_RE: RegExp;
+type ValidateDeviceInitiateResult = {
+    ok: true;
+    returnUrl: string;
+} | {
+    ok: false;
+    reason: string;
+};
+type DeviceApprovalTuple = {
+    userCode: string;
+    publicClientId: string;
+} | {
+    error: string;
+};
+/**
+ * Validate OP-issued `iss` + `target_link_uri` before storing a device approval cookie.
+ */
+declare function validateDeviceInitiateLogin(input: {
+    expectedIssuerUrl: string;
+    iss: string;
+    targetLinkUri: string;
+}): ValidateDeviceInitiateResult;
+/**
+ * Parse PymtHouse `/oidc/device` URL query for `user_code` + `client_id`.
+ */
+declare function extractDeviceApprovalFromTargetLink(targetHref: string, opts?: {
+    expectedIssuerUrl?: string;
+    expectedPublicClientId?: string;
+}): DeviceApprovalTuple;
+
+export { type DeviceApprovalTuple, USER_CODE_RE, type ValidateDeviceInitiateResult, extractDeviceApprovalFromTargetLink, validateDeviceInitiateLogin };

package/dist/device-initiate.js

@@ -0,0 +1,84 @@
+// 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/device-initiate.ts
+var USER_CODE_RE = /^(?=.*[A-Z0-9])[A-Z0-9-]{4,16}$/;
+function normalizeIssuerUrl(iss) {
+  try {
+    return stripTrailingSlashes(new URL(iss.trim()).href);
+  } catch {
+    return iss.trim();
+  }
+}
+function validateDeviceInitiateLogin(input) {
+  const expectedIss = stripTrailingSlashes(input.expectedIssuerUrl.trim());
+  let opOrigin;
+  try {
+    opOrigin = new URL(expectedIss).origin;
+  } catch {
+    return { ok: false, reason: "server_not_configured" };
+  }
+  if (normalizeIssuerUrl(input.iss) !== normalizeIssuerUrl(expectedIss)) {
+    return { ok: false, reason: "iss_mismatch" };
+  }
+  let target;
+  try {
+    target = new URL(input.targetLinkUri);
+  } catch {
+    return { ok: false, reason: "bad_target_uri" };
+  }
+  if (target.origin !== opOrigin) {
+    return { ok: false, reason: "target_origin_mismatch" };
+  }
+  if (target.pathname !== "/oidc/device") {
+    return { ok: false, reason: "target_path_mismatch" };
+  }
+  if (target.hash) {
+    return { ok: false, reason: "target_has_hash" };
+  }
+  return { ok: true, returnUrl: target.href };
+}
+function extractDeviceApprovalFromTargetLink(targetHref, opts) {
+  let target;
+  try {
+    target = new URL(targetHref);
+  } catch {
+    return { error: "bad_target_uri" };
+  }
+  if (opts?.expectedIssuerUrl) {
+    let opOrigin;
+    try {
+      opOrigin = new URL(stripTrailingSlashes(opts.expectedIssuerUrl.trim())).origin;
+    } catch {
+      return { error: "target_origin_mismatch" };
+    }
+    if (target.origin !== opOrigin) {
+      return { error: "target_origin_mismatch" };
+    }
+  }
+  if (target.pathname !== "/oidc/device") {
+    return { error: "target_path_mismatch" };
+  }
+  const userCodeRaw = target.searchParams.get("user_code")?.trim() ?? "";
+  const clientIdRaw = target.searchParams.get("client_id")?.trim() ?? "";
+  if (!userCodeRaw || !USER_CODE_RE.test(userCodeRaw)) {
+    return { error: "invalid_user_code" };
+  }
+  if (!clientIdRaw?.startsWith("app_")) {
+    return { error: "invalid_client_id" };
+  }
+  if (opts?.expectedPublicClientId && clientIdRaw !== opts.expectedPublicClientId) {
+    return { error: "client_id_mismatch" };
+  }
+  return { userCode: userCodeRaw, publicClientId: clientIdRaw };
+}
+
+export { USER_CODE_RE, extractDeviceApprovalFromTargetLink, validateDeviceInitiateLogin };
+//# sourceMappingURL=device-initiate.js.map
+//# sourceMappingURL=device-initiate.js.map

package/dist/device-initiate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/string-utils.ts","../src/device-initiate.ts"],"names":[],"mappings":"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","file":"device-initiate.js","sourcesContent":["/** 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 { stripTrailingSlashes } from \"./string-utils.js\";\n\n/** RFC 8628 user codes: 4–16 chars, at least one alphanumeric (not all dashes). */\nexport const USER_CODE_RE = /^(?=.*[A-Z0-9])[A-Z0-9-]{4,16}$/;\n\nexport type ValidateDeviceInitiateResult =\n  | { ok: true; returnUrl: string }\n  | { ok: false; reason: string };\n\nexport type DeviceApprovalTuple =\n  | { userCode: string; publicClientId: string }\n  | { error: string };\n\nfunction normalizeIssuerUrl(iss: string): string {\n  try {\n    return stripTrailingSlashes(new URL(iss.trim()).href);\n  } catch {\n    return iss.trim();\n  }\n}\n\n/**\n * Validate OP-issued `iss` + `target_link_uri` before storing a device approval cookie.\n */\nexport function validateDeviceInitiateLogin(input: {\n  expectedIssuerUrl: string;\n  iss: string;\n  targetLinkUri: string;\n}): ValidateDeviceInitiateResult {\n  const expectedIss = stripTrailingSlashes(input.expectedIssuerUrl.trim());\n  let opOrigin: string;\n  try {\n    opOrigin = new URL(expectedIss).origin;\n  } catch {\n    return { ok: false, reason: \"server_not_configured\" };\n  }\n\n  if (normalizeIssuerUrl(input.iss) !== normalizeIssuerUrl(expectedIss)) {\n    return { ok: false, reason: \"iss_mismatch\" };\n  }\n\n  let target: URL;\n  try {\n    target = new URL(input.targetLinkUri);\n  } catch {\n    return { ok: false, reason: \"bad_target_uri\" };\n  }\n  if (target.origin !== opOrigin) {\n    return { ok: false, reason: \"target_origin_mismatch\" };\n  }\n  if (target.pathname !== \"/oidc/device\") {\n    return { ok: false, reason: \"target_path_mismatch\" };\n  }\n  if (target.hash) {\n    return { ok: false, reason: \"target_has_hash\" };\n  }\n  return { ok: true, returnUrl: target.href };\n}\n\n/**\n * Parse PymtHouse `/oidc/device` URL query for `user_code` + `client_id`.\n */\nexport function extractDeviceApprovalFromTargetLink(\n  targetHref: string,\n  opts?: { expectedIssuerUrl?: string; expectedPublicClientId?: string },\n): DeviceApprovalTuple {\n  let target: URL;\n  try {\n    target = new URL(targetHref);\n  } catch {\n    return { error: \"bad_target_uri\" };\n  }\n\n  if (opts?.expectedIssuerUrl) {\n    let opOrigin: string;\n    try {\n      opOrigin = new URL(stripTrailingSlashes(opts.expectedIssuerUrl.trim())).origin;\n    } catch {\n      return { error: \"target_origin_mismatch\" };\n    }\n    if (target.origin !== opOrigin) {\n      return { error: \"target_origin_mismatch\" };\n    }\n  }\n\n  if (target.pathname !== \"/oidc/device\") {\n    return { error: \"target_path_mismatch\" };\n  }\n\n  const userCodeRaw = target.searchParams.get(\"user_code\")?.trim() ?? \"\";\n  const clientIdRaw = target.searchParams.get(\"client_id\")?.trim() ?? \"\";\n  if (!userCodeRaw || !USER_CODE_RE.test(userCodeRaw)) {\n    return { error: \"invalid_user_code\" };\n  }\n  if (!clientIdRaw?.startsWith(\"app_\")) {\n    return { error: \"invalid_client_id\" };\n  }\n  if (opts?.expectedPublicClientId && clientIdRaw !== opts.expectedPublicClientId) {\n    return { error: \"client_id_mismatch\" };\n  }\n  return { userCode: userCodeRaw, publicClientId: clientIdRaw };\n}\n"]}

package/dist/device.d.cts

@@ -1,5 +1,5 @@
 import * as oauth4webapi from 'oauth4webapi';
-import { F as FetchLike } from './types-W9PJAspR.cjs';
+import { F as FetchLike } from './types-rKzVXvMu.cjs';
 
 interface PollDeviceTokenOptions {
     issuerUrl: string;

package/dist/device.d.ts

@@ -1,5 +1,5 @@
 import * as oauth4webapi from 'oauth4webapi';
-import { F as FetchLike } from './types-W9PJAspR.js';
+import { F as FetchLike } from './types-rKzVXvMu.js';
 
 interface PollDeviceTokenOptions {
     issuerUrl: string;