@pymthouse/builder-sdk 0.0.8 → 0.3.0

package/README.md

@@ -12,6 +12,8 @@ OAuth/OIDC protocol calls use **[oauth4webapi](https://github.com/panva/oauth4we
 pnpm add @pymthouse/builder-sdk
 ```
 
+Maintainers: see [docs/RELEASING.md](docs/RELEASING.md) for trusted publishing and re-running failed releases.
+
 ## Quick start
 
 ```ts
@@ -66,14 +68,94 @@ const signerSession = await client.mintUserSignerSessionToken({
 For advanced flows that already have a user JWT, call
 `exchangeForSignerSession({ userJwt })` directly.
 
+### Dashboard API keys (long-lived `pmth_*`)
+
+Create a key in the Dashboard **API keys** page, then exchange it for a signer
+session without repeating device login:
+
+```ts
+const session = await client.exchangeApiKeyForSignerSession({
+  apiKey: process.env.PMTH_API_KEY!,
+  facadeUrl: process.env.DASHBOARD_ORIGIN!, // e.g. https://dashboard.example.com
+  scope: "sign:job",
+});
+// session.access_token — opaque signer bearer for discovery / gateway
+```
+
+See `examples/stream-with-api-key.mjs` for a minimal Node script.
+
+## Browser gateway (optional module)
+
+Live Video-to-Video streaming from the browser uses a **same-origin HTTP segment relay**
+implemented in optional subpaths (not exported from the main entry):
+
+| Subpath | Use |
+|---------|-----|
+| `@pymthouse/builder-sdk/gateway` | Shared types |
+| `@pymthouse/builder-sdk/gateway/client` | `BrowserGatewayClient` for dashboard / browser apps |
+| `@pymthouse/builder-sdk/gateway/server` | Route Handler factories for Next.js |
+
+Install peer dependencies when using the server module:
+
+```bash
+pnpm add @grpc/grpc-js @grpc/proto-loader
+```
+
+Auth flow (same signer bearer as Python `livepeer-python-gateway`):
+
+1. `exchangeApiKeyForSignerSession({ apiKey, facadeUrl: dashboardOrigin })` or `POST /api/pymthouse/keys/exchange`
+2. `Authorization: Bearer <signer_token>` on `POST /api/gateway/sessions`
+
+Enable relay on the dashboard with `GATEWAY_ENABLED=1` and `NEXT_PUBLIC_GATEWAY_ENABLED=1`.
+
+See `examples/gateway-session-smoke.mjs` for a headless session start test.
+
+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
@@ -90,6 +172,28 @@ const summary = summarizeUsageForExternalUser(usage, externalUserId);
 // summary.requestCount, summary.feeWei (wei string)
 ```
 
+## Billing: plans, retail usage, signed-ticket ingest
+
+**Plans (apiVersion=2):** `listBillingProducts({ apiVersion: "2" })` returns `BillingProduct[]` with capability pricing and sync status. `syncBillingProduct(planId)` POSTs to OpenMeter.
+
+**Retail estimates:** `getUsage({ includeRetail: true, groupBy: "pipeline_model" })` adds `endUserBillableUsdMicros` / fiat rows when the active plan has retail rates.
+
+**Signed-ticket ingest (platform metering):** after a signer proxy response, call `ingestSignedTicket` or use `forwardWithOptionalMetering` with `metering: { mode: "pymthouse_hosted" }` on `createSignerProxyServer` — usage is stripped from the client response and POSTed to `POST /api/v1/apps/{id}/usage/signed-tickets`.
+
+**Routing:** `getSignerRouting()` returns `signerApiUrl`, `remoteDmzUrl`, `meteringMode`, and pattern hints for hosted vs platform-ingest vs BYO OpenMeter.
+
+**Allowances (OpenMeter):** Trial and manual USD micros allowance use OpenMeter entitlements — not a Postgres wei ledger.
+
+| Method | SDK | HTTP |
+|--------|-----|------|
+| Read balance | `getUsageBalance(externalUserId)` | `GET .../usage/balance?externalUserId=` |
+| Read allowance detail | `getUserAllowances(externalUserId)` | `GET .../users/{id}/allowances` |
+| Top-up grant | `grantUserAllowance(externalUserId, { amountUsdMicros, source })` | `POST .../users/{id}/allowances` |
+
+`grantUserCredits` / `getUserCredits` remain as **deprecated** aliases that call the allowances / balance endpoints. `POST .../users/{id}/credits` was removed from PymtHouse (the route may still re-export allowances temporarily).
+
+**Plan pricing helpers:** `markupPercentToRetailRateUsd`, `applyRetailRateToNetworkMicros` (exported from the main entry).
+
 ## Usage API: pipeline/model grouping
 
 When `getUsage({ groupBy: "pipeline_model", startDate, endDate, userId })` returns

package/dist/client-BHfjDvIe.d.ts

@@ -0,0 +1,129 @@
+import { SignerSessionToken } from './tokens.js';
+import { P as PmtHouseClientOptions, G as GetDiscoveryOptions, O as OidcDiscoveryDocument, a as ParsedDeviceApprovalRedirect, A as AppUserRecord, U as UpsertAppUserInput, M as MintUserAccessTokenInput, b as MintUserAccessTokenResponse, T as TokenExchangeResponse, D as DeviceApprovalInput, C as ClientCredentialsTokenResponse, c as MintUserSignerSessionTokenInput, d as UsageQueryInput, e as UsageApiResponse, S as SignedTicketIngestInput, f as SignedTicketIngestResult, g as SignerRoutingResponse, L as ListBillingProductsResult, h as PlanSyncResult, i as UsageBalanceResponse, j as UserAllowancesResponse, k as UserAllowanceGrantInput, l as GrantSource, m as UserSubscriptionResponse, n as MeScopeUsagePayload, o as GetAppManifestResult, p as MintSignerSessionForExternalUserInput, q as ApproveDeviceLoginInput } from './types-_R1AwEZp.js';
+
+/**
+ * Normalize RFC 8628 user codes for comparison and resource URIs (uppercase, strip separators).
+ */
+declare function normalizeUserCode(value: string): string;
+/**
+ * RFC 8707 resource indicator for NaaP Option B device approval (`urn:pmth:device_code:<normalized>`).
+ */
+declare function buildDeviceCodeResource(userCode: string): string;
+declare class PmtHouseClient {
+    private readonly issuerUrl;
+    private readonly publicClientId;
+    private readonly m2mClientId;
+    private readonly m2mClientSecret;
+    private readonly fetchImpl;
+    private readonly logger?;
+    private readonly allowInsecureHttp;
+    constructor(options: PmtHouseClientOptions);
+    getDiscovery(options?: GetDiscoveryOptions): Promise<OidcDiscoveryDocument>;
+    verifyIssuer(iss: string): boolean;
+    parseDeviceApprovalRedirect(searchParams: URLSearchParams): ParsedDeviceApprovalRedirect;
+    listAppUsers(): Promise<{
+        users: AppUserRecord[];
+    }>;
+    upsertAppUser(input: UpsertAppUserInput): Promise<AppUserRecord>;
+    deleteAppUser(params: {
+        externalUserId: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    mintUserAccessToken(input: MintUserAccessTokenInput): Promise<MintUserAccessTokenResponse>;
+    /**
+     * Exchange a long-lived dashboard API key (`pmth_*`) for a short-lived user JWT.
+     */
+    exchangeApiKeyForUserAccessToken(input: {
+        apiKey: string;
+        scope?: string;
+    }): Promise<MintUserAccessTokenResponse>;
+    /**
+     * Exchange a dashboard API key for a signer session via a trusted facade (recommended)
+     * or directly when M2M credentials are available on this client.
+     */
+    exchangeApiKeyForSignerSession(input: {
+        apiKey: string;
+        scope?: string;
+        facadeUrl?: string;
+    }): Promise<TokenExchangeResponse>;
+    completeDeviceApproval(input: DeviceApprovalInput): Promise<TokenExchangeResponse>;
+    issueMachineAccessToken(scope?: string): Promise<ClientCredentialsTokenResponse>;
+    exchangeForSignerSession(input: {
+        userJwt: string;
+        resource?: string;
+    }): Promise<TokenExchangeResponse>;
+    /**
+     * Mint a short-lived per-user JWT with the Builder API, then exchange it for
+     * a long-lived opaque signer session token at the PymtHouse OIDC token endpoint.
+     */
+    mintUserSignerSessionToken(input: MintUserSignerSessionTokenInput): Promise<TokenExchangeResponse>;
+    createSignerSessionToken(params: {
+        userJwt?: string;
+    }): Promise<TokenExchangeResponse>;
+    getUsage(input?: UsageQueryInput): Promise<UsageApiResponse>;
+    /**
+     * Session-scoped usage for one `externalUserId`: user rollup plus merged pipeline/model breakdown.
+     */
+    ingestSignedTicket(ticket: SignedTicketIngestInput): Promise<SignedTicketIngestResult>;
+    ingestSignedTickets(tickets: SignedTicketIngestInput[]): Promise<{
+        results: Array<SignedTicketIngestResult & {
+            requestId?: string;
+            ok?: boolean;
+        }>;
+    }>;
+    getSignerRouting(): Promise<SignerRoutingResponse>;
+    listBillingProducts(): Promise<ListBillingProductsResult>;
+    syncBillingProduct(planId: string): Promise<PlanSyncResult>;
+    getUsageBalance(externalUserId: string): Promise<UsageBalanceResponse>;
+    getUserAllowances(externalUserId: string): Promise<UserAllowancesResponse>;
+    grantUserAllowance(externalUserId: string, input: UserAllowanceGrantInput): Promise<UserAllowancesResponse & {
+        grantedUsdMicros?: string;
+        featureKey?: string;
+    }>;
+    /**
+     * @deprecated Removed from PymtHouse — use {@link getUsageBalance} or {@link getUserAllowances}.
+     */
+    getUserCredits(externalUserId: string): Promise<UsageBalanceResponse>;
+    /**
+     * @deprecated Removed from PymtHouse — use {@link grantUserAllowance} (`POST .../allowances`).
+     */
+    grantUserCredits(externalUserId: string, input: {
+        amountUsdMicros: string;
+        source?: GrantSource;
+        featureKey?: string;
+    }): Promise<UsageBalanceResponse & {
+        grantedUsdMicros?: string;
+        featureKey?: string;
+    }>;
+    getUserSubscription(externalUserId: string): Promise<UserSubscriptionResponse>;
+    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;
+}
+
+export { PmtHouseClient as P, buildDeviceCodeResource as b, normalizeUserCode as n };

package/dist/client-CvhJEhjV.d.cts

@@ -0,0 +1,129 @@
+import { SignerSessionToken } from './tokens.cjs';
+import { P as PmtHouseClientOptions, G as GetDiscoveryOptions, O as OidcDiscoveryDocument, a as ParsedDeviceApprovalRedirect, A as AppUserRecord, U as UpsertAppUserInput, M as MintUserAccessTokenInput, b as MintUserAccessTokenResponse, T as TokenExchangeResponse, D as DeviceApprovalInput, C as ClientCredentialsTokenResponse, c as MintUserSignerSessionTokenInput, d as UsageQueryInput, e as UsageApiResponse, S as SignedTicketIngestInput, f as SignedTicketIngestResult, g as SignerRoutingResponse, L as ListBillingProductsResult, h as PlanSyncResult, i as UsageBalanceResponse, j as UserAllowancesResponse, k as UserAllowanceGrantInput, l as GrantSource, m as UserSubscriptionResponse, n as MeScopeUsagePayload, o as GetAppManifestResult, p as MintSignerSessionForExternalUserInput, q as ApproveDeviceLoginInput } from './types-_R1AwEZp.cjs';
+
+/**
+ * Normalize RFC 8628 user codes for comparison and resource URIs (uppercase, strip separators).
+ */
+declare function normalizeUserCode(value: string): string;
+/**
+ * RFC 8707 resource indicator for NaaP Option B device approval (`urn:pmth:device_code:<normalized>`).
+ */
+declare function buildDeviceCodeResource(userCode: string): string;
+declare class PmtHouseClient {
+    private readonly issuerUrl;
+    private readonly publicClientId;
+    private readonly m2mClientId;
+    private readonly m2mClientSecret;
+    private readonly fetchImpl;
+    private readonly logger?;
+    private readonly allowInsecureHttp;
+    constructor(options: PmtHouseClientOptions);
+    getDiscovery(options?: GetDiscoveryOptions): Promise<OidcDiscoveryDocument>;
+    verifyIssuer(iss: string): boolean;
+    parseDeviceApprovalRedirect(searchParams: URLSearchParams): ParsedDeviceApprovalRedirect;
+    listAppUsers(): Promise<{
+        users: AppUserRecord[];
+    }>;
+    upsertAppUser(input: UpsertAppUserInput): Promise<AppUserRecord>;
+    deleteAppUser(params: {
+        externalUserId: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    mintUserAccessToken(input: MintUserAccessTokenInput): Promise<MintUserAccessTokenResponse>;
+    /**
+     * Exchange a long-lived dashboard API key (`pmth_*`) for a short-lived user JWT.
+     */
+    exchangeApiKeyForUserAccessToken(input: {
+        apiKey: string;
+        scope?: string;
+    }): Promise<MintUserAccessTokenResponse>;
+    /**
+     * Exchange a dashboard API key for a signer session via a trusted facade (recommended)
+     * or directly when M2M credentials are available on this client.
+     */
+    exchangeApiKeyForSignerSession(input: {
+        apiKey: string;
+        scope?: string;
+        facadeUrl?: string;
+    }): Promise<TokenExchangeResponse>;
+    completeDeviceApproval(input: DeviceApprovalInput): Promise<TokenExchangeResponse>;
+    issueMachineAccessToken(scope?: string): Promise<ClientCredentialsTokenResponse>;
+    exchangeForSignerSession(input: {
+        userJwt: string;
+        resource?: string;
+    }): Promise<TokenExchangeResponse>;
+    /**
+     * Mint a short-lived per-user JWT with the Builder API, then exchange it for
+     * a long-lived opaque signer session token at the PymtHouse OIDC token endpoint.
+     */
+    mintUserSignerSessionToken(input: MintUserSignerSessionTokenInput): Promise<TokenExchangeResponse>;
+    createSignerSessionToken(params: {
+        userJwt?: string;
+    }): Promise<TokenExchangeResponse>;
+    getUsage(input?: UsageQueryInput): Promise<UsageApiResponse>;
+    /**
+     * Session-scoped usage for one `externalUserId`: user rollup plus merged pipeline/model breakdown.
+     */
+    ingestSignedTicket(ticket: SignedTicketIngestInput): Promise<SignedTicketIngestResult>;
+    ingestSignedTickets(tickets: SignedTicketIngestInput[]): Promise<{
+        results: Array<SignedTicketIngestResult & {
+            requestId?: string;
+            ok?: boolean;
+        }>;
+    }>;
+    getSignerRouting(): Promise<SignerRoutingResponse>;
+    listBillingProducts(): Promise<ListBillingProductsResult>;
+    syncBillingProduct(planId: string): Promise<PlanSyncResult>;
+    getUsageBalance(externalUserId: string): Promise<UsageBalanceResponse>;
+    getUserAllowances(externalUserId: string): Promise<UserAllowancesResponse>;
+    grantUserAllowance(externalUserId: string, input: UserAllowanceGrantInput): Promise<UserAllowancesResponse & {
+        grantedUsdMicros?: string;
+        featureKey?: string;
+    }>;
+    /**
+     * @deprecated Removed from PymtHouse — use {@link getUsageBalance} or {@link getUserAllowances}.
+     */
+    getUserCredits(externalUserId: string): Promise<UsageBalanceResponse>;
+    /**
+     * @deprecated Removed from PymtHouse — use {@link grantUserAllowance} (`POST .../allowances`).
+     */
+    grantUserCredits(externalUserId: string, input: {
+        amountUsdMicros: string;
+        source?: GrantSource;
+        featureKey?: string;
+    }): Promise<UsageBalanceResponse & {
+        grantedUsdMicros?: string;
+        featureKey?: string;
+    }>;
+    getUserSubscription(externalUserId: string): Promise<UserSubscriptionResponse>;
+    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;
+}
+
+export { PmtHouseClient as P, buildDeviceCodeResource as b, normalizeUserCode as n };

package/dist/config.cjs

@@ -0,0 +1,122 @@
+'use strict';
+
+// src/string-utils.ts
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && (value.codePointAt(end - 1) ?? 0) === 47) {
+    end--;
+  }
+  return value.slice(0, end);
+}
+function endsWithIgnoreCase(value, suffix) {
+  if (suffix.length > value.length) {
+    return false;
+  }
+  const start = value.length - suffix.length;
+  for (let i = 0; i < suffix.length; i++) {
+    const a = value.codePointAt(start + i) ?? 0;
+    const b = suffix.codePointAt(i) ?? 0;
+    if (a !== b && (a | 32) !== (b | 32)) {
+      return false;
+    }
+  }
+  return true;
+}
+function stripSuffixIgnoreCase(value, suffix) {
+  return endsWithIgnoreCase(value, suffix) ? value.slice(0, value.length - suffix.length) : value;
+}
+function stripOidcPathSuffix(issuerUrl) {
+  let base = stripTrailingSlashes(issuerUrl.trim());
+  base = stripSuffixIgnoreCase(base, "/oidc");
+  return stripTrailingSlashes(base);
+}
+function isSafePathSegment(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 128) {
+    return false;
+  }
+  for (let i = 0; i < value.length; i++) {
+    const c = value.codePointAt(i) ?? 0;
+    const ok = c >= 48 && c <= 57 || c >= 65 && c <= 90 || c >= 97 && c <= 122 || c === 95 || c === 45;
+    if (!ok) {
+      return false;
+    }
+  }
+  return true;
+}
+function parseHttpOrigin(raw, fallback) {
+  const trimmed = (raw ?? fallback).trim();
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new TypeError("Origin must be a valid http(s) URL");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new TypeError("Origin must use http or https");
+  }
+  return parsed.origin;
+}
+function buildGatewaySessionDeleteUrl(origin, sessionId) {
+  if (!isSafePathSegment(sessionId)) {
+    throw new TypeError("Invalid gateway session id");
+  }
+  return new URL(`/api/gateway/sessions/${encodeURIComponent(sessionId)}`, origin);
+}
+
+// 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) {
+  return stripOidcPathSuffix(issuerUrl);
+}
+function getPymthouseIssuerOrigin(issuerUrl) {
+  return new URL(stripTrailingSlashes(issuerUrl.trim())).origin;
+}
+
+exports.PYMTHOUSE_NOT_CONFIGURED_MESSAGE = PYMTHOUSE_NOT_CONFIGURED_MESSAGE;
+exports.buildGatewaySessionDeleteUrl = buildGatewaySessionDeleteUrl;
+exports.getBuilderApiV1BaseFromIssuerUrl = getBuilderApiV1BaseFromIssuerUrl;
+exports.getPymthouseIssuerOrigin = getPymthouseIssuerOrigin;
+exports.getPymthouseIssuerUrlFromEnv = getPymthouseIssuerUrlFromEnv;
+exports.getPymthousePublicClientIdFromEnv = getPymthousePublicClientIdFromEnv;
+exports.isPymthouseConfigured = isPymthouseConfigured;
+exports.isSafePathSegment = isSafePathSegment;
+exports.parseHttpOrigin = parseHttpOrigin;
+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,GAAA,GAAM,MAAM,KAAA,CAAM,WAAA,CAAY,MAAM,CAAC,CAAA,IAAK,OAAO,EAAA,EAAI;AAC1D,IAAA,GAAA,EAAA;AAAA,EACF;AACA,EAAA,OAAO,KAAA,CAAM,KAAA,CAAM,CAAA,EAAG,GAAG,CAAA;AAC3B;AAEA,SAAS,kBAAA,CAAmB,OAAe,MAAA,EAAyB;AAClE,EAAA,IAAI,MAAA,CAAO,MAAA,GAAS,KAAA,CAAM,MAAA,EAAQ;AAChC,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,MAAA,GAAS,MAAA,CAAO,MAAA;AACpC,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,MAAA,CAAO,QAAQ,CAAA,EAAA,EAAK;AACtC,IAAA,MAAM,CAAA,GAAI,KAAA,CAAM,WAAA,CAAY,KAAA,GAAQ,CAAC,CAAA,IAAK,CAAA;AAC1C,IAAA,MAAM,CAAA,GAAI,MAAA,CAAO,WAAA,CAAY,CAAC,CAAA,IAAK,CAAA;AACnC,IAAA,IAAI,CAAA,KAAM,CAAA,IAAA,CAAM,CAAA,GAAI,EAAA,OAAS,IAAI,EAAA,CAAA,EAAK;AACpC,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AACA,EAAA,OAAO,IAAA;AACT;AAEA,SAAS,qBAAA,CAAsB,OAAe,MAAA,EAAwB;AACpE,EAAA,OAAO,kBAAA,CAAmB,KAAA,EAAO,MAAM,CAAA,GACnC,KAAA,CAAM,KAAA,CAAM,CAAA,EAAG,KAAA,CAAM,MAAA,GAAS,MAAA,CAAO,MAAM,CAAA,GAC3C,KAAA;AACN;AAGO,SAAS,oBAAoB,SAAA,EAA2B;AAC7D,EAAA,IAAI,IAAA,GAAO,oBAAA,CAAqB,SAAA,CAAU,IAAA,EAAM,CAAA;AAChD,EAAA,IAAA,GAAO,qBAAA,CAAsB,MAAM,OAAO,CAAA;AAC1C,EAAA,OAAO,qBAAqB,IAAI,CAAA;AAClC;AAWO,SAAS,kBAAkB,KAAA,EAAiC;AACjE,EAAA,IAAI,OAAO,UAAU,QAAA,IAAY,KAAA,CAAM,WAAW,CAAA,IAAK,KAAA,CAAM,SAAS,GAAA,EAAK;AACzE,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,QAAQ,CAAA,EAAA,EAAK;AACrC,IAAA,MAAM,CAAA,GAAI,KAAA,CAAM,WAAA,CAAY,CAAC,CAAA,IAAK,CAAA;AAClC,IAAA,MAAM,EAAA,GACH,CAAA,IAAK,EAAA,IAAM,CAAA,IAAK,MAChB,CAAA,IAAK,EAAA,IAAM,CAAA,IAAK,EAAA,IAChB,KAAK,EAAA,IAAM,CAAA,IAAK,GAAA,IACjB,CAAA,KAAM,MACN,CAAA,KAAM,EAAA;AACR,IAAA,IAAI,CAAC,EAAA,EAAI;AACP,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AACA,EAAA,OAAO,IAAA;AACT;AAGO,SAAS,eAAA,CAAgB,KAAyB,QAAA,EAA0B;AACjF,EAAA,MAAM,OAAA,GAAA,CAAW,GAAA,IAAO,QAAA,EAAU,IAAA,EAAK;AACvC,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,IAAI,IAAI,OAAO,CAAA;AAAA,EAC1B,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,UAAU,oCAAoC,CAAA;AAAA,EAC1D;AACA,EAAA,IAAI,MAAA,CAAO,QAAA,KAAa,OAAA,IAAW,MAAA,CAAO,aAAa,QAAA,EAAU;AAC/D,IAAA,MAAM,IAAI,UAAU,+BAA+B,CAAA;AAAA,EACrD;AACA,EAAA,OAAO,MAAA,CAAO,MAAA;AAChB;AAGO,SAAS,4BAAA,CAA6B,QAAgB,SAAA,EAAwB;AACnF,EAAA,IAAI,CAAC,iBAAA,CAAkB,SAAS,CAAA,EAAG;AACjC,IAAA,MAAM,IAAI,UAAU,4BAA4B,CAAA;AAAA,EAClD;AACA,EAAA,OAAO,IAAI,GAAA,CAAI,CAAA,sBAAA,EAAyB,mBAAmB,SAAS,CAAC,IAAI,MAAM,CAAA;AACjF;;;AC3EO,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,OAAO,oBAAoB,SAAS,CAAA;AACtC;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.codePointAt(end - 1) ?? 0) === 47) {\n    end--;\n  }\n  return value.slice(0, end);\n}\n\nfunction endsWithIgnoreCase(value: string, suffix: string): boolean {\n  if (suffix.length > value.length) {\n    return false;\n  }\n  const start = value.length - suffix.length;\n  for (let i = 0; i < suffix.length; i++) {\n    const a = value.codePointAt(start + i) ?? 0;\n    const b = suffix.codePointAt(i) ?? 0;\n    if (a !== b && (a | 32) !== (b | 32)) {\n      return false;\n    }\n  }\n  return true;\n}\n\nfunction stripSuffixIgnoreCase(value: string, suffix: string): string {\n  return endsWithIgnoreCase(value, suffix)\n    ? value.slice(0, value.length - suffix.length)\n    : value;\n}\n\n/** Issuer URL (`…/oidc`) → Builder API base (`…/api/v1`). Linear-time; no regex. */\nexport function stripOidcPathSuffix(issuerUrl: string): string {\n  let base = stripTrailingSlashes(issuerUrl.trim());\n  base = stripSuffixIgnoreCase(base, \"/oidc\");\n  return stripTrailingSlashes(base);\n}\n\n/** Issuer URL (`…/api/v1/oidc`) → host origin for signer/API-key routes. Linear-time; no regex. */\nexport function stripIssuerOriginFromOidcUrl(issuerUrl: string): string {\n  let base = stripTrailingSlashes(issuerUrl.trim());\n  base = stripSuffixIgnoreCase(base, \"/api/v1/oidc\");\n  base = stripSuffixIgnoreCase(base, \"/oidc\");\n  return stripTrailingSlashes(base);\n}\n\n/** Validate gateway session ids before embedding in request URLs. */\nexport function isSafePathSegment(value: unknown): value is string {\n  if (typeof value !== \"string\" || value.length === 0 || value.length > 128) {\n    return false;\n  }\n  for (let i = 0; i < value.length; i++) {\n    const c = value.codePointAt(i) ?? 0;\n    const ok =\n      (c >= 48 && c <= 57) ||\n      (c >= 65 && c <= 90) ||\n      (c >= 97 && c <= 122) ||\n      c === 95 ||\n      c === 45;\n    if (!ok) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/** Parse and validate an http(s) facade origin (no path). */\nexport function parseHttpOrigin(raw: string | undefined, fallback: string): string {\n  const trimmed = (raw ?? fallback).trim();\n  let parsed: URL;\n  try {\n    parsed = new URL(trimmed);\n  } catch {\n    throw new TypeError(\"Origin must be a valid http(s) URL\");\n  }\n  if (parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") {\n    throw new TypeError(\"Origin must use http or https\");\n  }\n  return parsed.origin;\n}\n\n/** Build a validated DELETE URL for `/api/gateway/sessions/:id`. */\nexport function buildGatewaySessionDeleteUrl(origin: string, sessionId: string): URL {\n  if (!isSafePathSegment(sessionId)) {\n    throw new TypeError(\"Invalid gateway session id\");\n  }\n  return new URL(`/api/gateway/sessions/${encodeURIComponent(sessionId)}`, origin);\n}\n","import {\n  buildGatewaySessionDeleteUrl,\n  isSafePathSegment,\n  parseHttpOrigin,\n  stripOidcPathSuffix,\n  stripTrailingSlashes,\n} from \"./string-utils.js\";\n\nexport { buildGatewaySessionDeleteUrl, isSafePathSegment, parseHttpOrigin };\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  return stripOidcPathSuffix(issuerUrl);\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,29 @@
+/** Validate gateway session ids before embedding in request URLs. */
+declare function isSafePathSegment(value: unknown): value is string;
+/** Parse and validate an http(s) facade origin (no path). */
+declare function parseHttpOrigin(raw: string | undefined, fallback: string): string;
+/** Build a validated DELETE URL for `/api/gateway/sessions/:id`. */
+declare function buildGatewaySessionDeleteUrl(origin: string, sessionId: string): URL;
+
+/** 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, buildGatewaySessionDeleteUrl, getBuilderApiV1BaseFromIssuerUrl, getPymthouseIssuerOrigin, getPymthouseIssuerUrlFromEnv, getPymthousePublicClientIdFromEnv, isPymthouseConfigured, isSafePathSegment, parseHttpOrigin, readPymthouseEnv };

package/dist/config.d.ts

@@ -0,0 +1,29 @@
+/** Validate gateway session ids before embedding in request URLs. */
+declare function isSafePathSegment(value: unknown): value is string;
+/** Parse and validate an http(s) facade origin (no path). */
+declare function parseHttpOrigin(raw: string | undefined, fallback: string): string;
+/** Build a validated DELETE URL for `/api/gateway/sessions/:id`. */
+declare function buildGatewaySessionDeleteUrl(origin: string, sessionId: string): URL;
+
+/** 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, buildGatewaySessionDeleteUrl, getBuilderApiV1BaseFromIssuerUrl, getPymthouseIssuerOrigin, getPymthouseIssuerUrlFromEnv, getPymthousePublicClientIdFromEnv, isPymthouseConfigured, isSafePathSegment, parseHttpOrigin, readPymthouseEnv };