@zenglobal/api-client 5.0.9 → 5.0.11

package/README.md

@@ -93,14 +93,42 @@ Both error classes extend `Error`, so `instanceof Error` works for catch-all han
 
 ## Configuration Options
 
-| Option     | Type         | Default        | Description                        |
-| ---------- | ------------ | -------------- | ---------------------------------- |
-| `baseUrl`  | `string`     | —              | Zen API base URL                   |
-| `username` | `string`     | —              | HTTP Basic Auth username           |
-| `password` | `string`     | —              | HTTP Basic Auth password           |
-| `partner`  | `ZenPartner` | —              | Partner identification (see below) |
-| `timeout`  | `number`     | `30000`        | Request timeout in ms              |
-| `retry`    | `object`     | `{ limit: 3 }` | Retry configuration                |
+| Option     | Type         | Default        | Description                                                            |
+| ---------- | ------------ | -------------- | ---------------------------------------------------------------------- |
+| `baseUrl`  | `string`     | —              | Zen API base URL                                                       |
+| `username` | `string`     | —              | HTTP Basic Auth username (or use `auth`)                               |
+| `password` | `string`     | —              | HTTP Basic Auth password (or use `auth`)                               |
+| `auth`     | `ZenAuth`    | —              | OAuth 2.0 client_credentials config (alternative to username/password) |
+| `partner`  | `ZenPartner` | —              | Partner identification (see below)                                     |
+| `timeout`  | `number`     | `30000`        | Request timeout in ms                                                  |
+| `retry`    | `object`     | `{ limit: 3 }` | Retry configuration                                                    |
+
+### OAuth client_credentials
+
+Instead of HTTP Basic, the client can authenticate with the OAuth 2.0
+`client_credentials` grant. The existing Partner API key **is**
+the OAuth client (`clientId` = key username, `clientSecret` = key password).
+The client mints a `zen-partner-api` Bearer token from the auth host, caches it
+in memory, refreshes it before expiry, and (for idempotent requests) refreshes
+and retries once on a 401.
+
+```typescript
+configureZenClient({
+  baseUrl: "https://api.zenglobal.au/v1",
+  partner: { partnerId: "q74vzg9o", name: "my-pos-app", version: "1.0.0" },
+  auth: {
+    mode: "clientCredentials",
+    clientId: process.env.ZEN_CLIENT_ID,
+    clientSecret: process.env.ZEN_CLIENT_SECRET,
+    // scope: "read write",  // optional; space-delimited
+    // tokenUrl: "https://auth.zendev.au/oauth/token", // override for dev/staging
+  },
+});
+```
+
+The token endpoint defaults to `https://auth.zenglobal.au/oauth/token` (a
+separate host from `baseUrl`). Override it via `auth.tokenUrl` for local or
+staging environments. Token-endpoint failures throw `ZenAuthError`.
 
 ### Partner Identification
 

package/dist/__tests__/mocks/handlers/loyalty.d.ts

@@ -0,0 +1,2 @@
+export declare const handlers: import("msw").HttpHandler[];
+//# sourceMappingURL=loyalty.d.ts.map

package/dist/__tests__/mocks/handlers/loyalty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loyalty.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/mocks/handlers/loyalty.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ,6BAkBpB,CAAC"}

package/dist/__tests__/mocks/handlers/loyalty.js

@@ -0,0 +1,21 @@
+import { http, HttpResponse } from 'msw';
+export const handlers = [
+    http.get('*/Loyalty/Card/:cardNumber', ({ params }) => {
+        const cardNumber = params.cardNumber;
+        if (cardNumber === 'NOT_FOUND') {
+            return HttpResponse.json({
+                result: 4,
+                errormessage: 'Card not found',
+            });
+        }
+        return HttpResponse.json({
+            result: 0,
+            CardNumber: cardNumber,
+            FirstName: 'Jane',
+            LastName: 'Doe',
+            Points: 500,
+            Status: 'Active',
+        });
+    }),
+];
+//# sourceMappingURL=loyalty.js.map

package/dist/__tests__/mocks/handlers/loyalty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loyalty.js","sourceRoot":"","sources":["../../../../src/__tests__/mocks/handlers/loyalty.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AAEzC,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,IAAI,CAAC,GAAG,CAAC,4BAA4B,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;QACpD,MAAM,UAAU,GAAG,MAAM,CAAC,UAAoB,CAAC;QAC/C,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;YAC/B,OAAO,YAAY,CAAC,IAAI,CAAC;gBACvB,MAAM,EAAE,CAAC;gBACT,YAAY,EAAE,gBAAgB;aAC/B,CAAC,CAAC;QACL,CAAC;QACD,OAAO,YAAY,CAAC,IAAI,CAAC;YACvB,MAAM,EAAE,CAAC;YACT,UAAU,EAAE,UAAU;YACtB,SAAS,EAAE,MAAM;YACjB,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,GAAG;YACX,MAAM,EAAE,QAAQ;SACjB,CAAC,CAAC;IACL,CAAC,CAAC;CACH,CAAC"}

package/dist/__tests__/mocks/handlers/ping.d.ts

@@ -0,0 +1,2 @@
+export declare const handlers: import("msw").HttpHandler[];
+//# sourceMappingURL=ping.d.ts.map

package/dist/__tests__/mocks/handlers/ping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ping.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/mocks/handlers/ping.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ,6BAIpB,CAAC"}

package/dist/__tests__/mocks/handlers/ping.js

@@ -0,0 +1,5 @@
+import { http, HttpResponse } from 'msw';
+export const handlers = [
+    http.get('*/ping', () => HttpResponse.json({ result: 0, version: '1.0.0' })),
+];
+//# sourceMappingURL=ping.js.map

package/dist/__tests__/mocks/handlers/ping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ping.js","sourceRoot":"","sources":["../../../../src/__tests__/mocks/handlers/ping.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AAEzC,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE,CACtB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CACnD;CACF,CAAC"}

package/dist/__tests__/mocks/handlers/voucher.d.ts

@@ -0,0 +1,2 @@
+export declare const handlers: import("msw").HttpHandler[];
+//# sourceMappingURL=voucher.d.ts.map

package/dist/__tests__/mocks/handlers/voucher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voucher.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/mocks/handlers/voucher.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ,6BA+BpB,CAAC"}

package/dist/__tests__/mocks/handlers/voucher.js

@@ -0,0 +1,33 @@
+import { http, HttpResponse } from 'msw';
+export const handlers = [
+    http.post('*/voucher/:voucherType/enquire', async ({ request }) => {
+        const body = await request.json();
+        const serial = body?.voucher?.serialnumber;
+        if (serial === 'EXPIRED') {
+            return HttpResponse.json({
+                result: 9,
+                errormessage: 'Voucher has expired',
+                reason: 'Expired',
+            });
+        }
+        return HttpResponse.json({
+            result: 0,
+            voucher: {
+                serialnumber: serial,
+                balance: 50.0,
+                status: 'Active',
+            },
+        });
+    }),
+    http.post('*/SMS', async ({ request }) => {
+        const body = await request.json();
+        if (!body.sms) {
+            return HttpResponse.json({
+                result: 8,
+                errormessage: 'Body Missing',
+            });
+        }
+        return HttpResponse.json({ result: 0 });
+    }),
+];
+//# sourceMappingURL=voucher.js.map

package/dist/__tests__/mocks/handlers/voucher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voucher.js","sourceRoot":"","sources":["../../../../src/__tests__/mocks/handlers/voucher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AAEzC,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,IAAI,CAAC,IAAI,CAAC,gCAAgC,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QAChE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAA6C,CAAC;QAC7E,MAAM,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC;QAC3C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,YAAY,CAAC,IAAI,CAAC;gBACvB,MAAM,EAAE,CAAC;gBACT,YAAY,EAAE,qBAAqB;gBACnC,MAAM,EAAE,SAAS;aAClB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,YAAY,CAAC,IAAI,CAAC;YACvB,MAAM,EAAE,CAAC;YACT,OAAO,EAAE;gBACP,YAAY,EAAE,MAAM;gBACpB,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,QAAQ;aACjB;SACF,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACvC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAA6B,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,OAAO,YAAY,CAAC,IAAI,CAAC;gBACvB,MAAM,EAAE,CAAC;gBACT,YAAY,EAAE,cAAc;aAC7B,CAAC,CAAC;QACL,CAAC;QACD,OAAO,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC;CACH,CAAC"}

package/dist/__tests__/mocks/handlers.d.ts

@@ -0,0 +1,2 @@
+export declare const handlers: import("msw").HttpHandler[];
+//# sourceMappingURL=handlers.d.ts.map

package/dist/__tests__/mocks/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/__tests__/mocks/handlers.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,QAAQ,6BAIpB,CAAC"}

package/dist/__tests__/mocks/handlers.js

@@ -0,0 +1,9 @@
+import { handlers as pingHandlers } from './handlers/ping.js';
+import { handlers as loyaltyHandlers } from './handlers/loyalty.js';
+import { handlers as voucherHandlers } from './handlers/voucher.js';
+export const handlers = [
+    ...pingHandlers,
+    ...loyaltyHandlers,
+    ...voucherHandlers,
+];
+//# sourceMappingURL=handlers.js.map

package/dist/__tests__/mocks/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../src/__tests__/mocks/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEpE,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,GAAG,YAAY;IACf,GAAG,eAAe;IAClB,GAAG,eAAe;CACnB,CAAC"}

package/dist/__tests__/mocks/node.d.ts

@@ -0,0 +1,3 @@
+declare const server: import("msw/node").SetupServerApi;
+export default server;
+//# sourceMappingURL=node.d.ts.map

package/dist/__tests__/mocks/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/__tests__/mocks/node.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,MAAM,mCAA2B,CAAC;AACxC,eAAe,MAAM,CAAC"}

package/dist/__tests__/mocks/node.js

@@ -0,0 +1,5 @@
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers.js';
+const server = setupServer(...handlers);
+export default server;
+//# sourceMappingURL=node.js.map

package/dist/__tests__/mocks/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../../src/__tests__/mocks/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC;AACxC,eAAe,MAAM,CAAC"}

package/dist/auth/__tests__/tokenManager.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tokenManager.test.d.ts.map

package/dist/auth/__tests__/tokenManager.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenManager.test.d.ts","sourceRoot":"","sources":["../../../src/auth/__tests__/tokenManager.test.ts"],"names":[],"mappings":""}

package/dist/auth/__tests__/tokenManager.test.js

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { http, HttpResponse } from "msw";
+import server from "../../__tests__/mocks/node.js";
+import { TokenManager } from "../tokenManager.js";
+import { ZenAuthError } from "../../errors.js";
+const TOKEN_URL = "https://auth.test.example/oauth/token";
+function tokenHandler(opts) {
+    return http.post(TOKEN_URL, async ({ request }) => {
+        const text = await request.text();
+        opts.onHit?.(new URLSearchParams(text));
+        if (opts.status && opts.status >= 400) {
+            return HttpResponse.json({ error: "invalid_client" }, { status: opts.status });
+        }
+        return HttpResponse.json({
+            access_token: opts.token ?? "tok-1",
+            token_type: "Bearer",
+            expires_in: opts.expiresIn ?? 3600,
+        });
+    });
+}
+const baseConfig = {
+    clientId: "key-user",
+    clientSecret: "key-secret",
+    tokenUrl: TOKEN_URL,
+};
+afterEach(() => server.resetHandlers());
+describe("TokenManager", () => {
+    it("acquires a token with a client_credentials form body", async () => {
+        let seen;
+        server.use(tokenHandler({ token: "abc", onHit: (b) => (seen = b) }));
+        const tm = new TokenManager(baseConfig);
+        const token = await tm.getToken();
+        expect(token).toBe("abc");
+        expect(seen?.get("grant_type")).toBe("client_credentials");
+        expect(seen?.get("client_id")).toBe("key-user");
+        expect(seen?.get("client_secret")).toBe("key-secret");
+        expect(seen?.get("scope")).toBeNull();
+    });
+    it("includes scope when configured", async () => {
+        let seen;
+        server.use(tokenHandler({ onHit: (b) => (seen = b) }));
+        const tm = new TokenManager({ ...baseConfig, scope: "a b" });
+        await tm.getToken();
+        expect(seen?.get("scope")).toBe("a b");
+    });
+    it("caches the token and does not refetch before expiry", async () => {
+        let hits = 0;
+        server.use(tokenHandler({ onHit: () => (hits += 1) }));
+        let now = 0;
+        const tm = new TokenManager(baseConfig, { now: () => now });
+        await tm.getToken();
+        now = 1_000_000; // 1000s later, well inside a 3600s token
+        await tm.getToken();
+        expect(hits).toBe(1);
+    });
+    it("refetches once the skew window is entered", async () => {
+        let hits = 0;
+        server.use(tokenHandler({ expiresIn: 100, onHit: () => (hits += 1) }));
+        let now = 0;
+        const tm = new TokenManager(baseConfig, { now: () => now, skewMs: 30_000 });
+        await tm.getToken(); // expiresAt = 100_000ms
+        now = 71_000; // within 30s skew of expiry (100_000 - 30_000 = 70_000)
+        await tm.getToken();
+        expect(hits).toBe(2);
+    });
+    it("dedupes concurrent acquisitions into one fetch", async () => {
+        let hits = 0;
+        server.use(tokenHandler({ onHit: () => (hits += 1) }));
+        const tm = new TokenManager(baseConfig);
+        const [a, b] = await Promise.all([tm.getToken(), tm.getToken()]);
+        expect(a).toBe(b);
+        expect(hits).toBe(1);
+    });
+    it("refresh() forces a new fetch even within validity", async () => {
+        let hits = 0;
+        let token = "first";
+        server.use(http.post(TOKEN_URL, () => {
+            hits += 1;
+            const body = {
+                access_token: token,
+                token_type: "Bearer",
+                expires_in: 3600,
+            };
+            token = "second";
+            return HttpResponse.json(body);
+        }));
+        const tm = new TokenManager(baseConfig);
+        expect(await tm.getToken()).toBe("first");
+        expect(await tm.refresh()).toBe("second");
+        expect(hits).toBe(2);
+    });
+    it("throws ZenAuthError on a non-2xx token response", async () => {
+        server.use(tokenHandler({ status: 401 }));
+        const tm = new TokenManager(baseConfig);
+        await expect(tm.getToken()).rejects.toBeInstanceOf(ZenAuthError);
+    });
+    it("throws ZenAuthError when the token endpoint is unreachable", async () => {
+        server.use(http.post(TOKEN_URL, () => HttpResponse.error()));
+        const tm = new TokenManager(baseConfig);
+        await expect(tm.getToken()).rejects.toBeInstanceOf(ZenAuthError);
+    });
+});
+//# sourceMappingURL=tokenManager.test.js.map

package/dist/auth/__tests__/tokenManager.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenManager.test.js","sourceRoot":"","sources":["../../../src/auth/__tests__/tokenManager.test.ts"],"names":[],"mappings":"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"}

package/dist/auth/tokenManager.d.ts

@@ -0,0 +1,42 @@
+export interface ClientCredentials {
+    /** OAuth client id (the Partner API key username under model C). */
+    clientId: string;
+    /** OAuth client secret (the Partner API key password). */
+    clientSecret: string;
+    /** Optional space-delimited scope string. */
+    scope?: string;
+    /** Fully-resolved token endpoint URL. */
+    tokenUrl: string;
+}
+interface TokenManagerOptions {
+    /** Override fetch (defaults to globalThis.fetch). */
+    fetch?: typeof globalThis.fetch;
+    /** Treat the token as expired this many ms before its real expiry. */
+    skewMs?: number;
+    /** Clock source (defaults to Date.now); injectable for tests. */
+    now?: () => number;
+}
+/**
+ * Owns the OAuth client_credentials token lifecycle for one client:
+ * acquisition, in-memory caching, proactive skew-based refresh, single
+ * in-flight de-duplication, and forced refresh after a 401.
+ */
+export declare class TokenManager {
+    private readonly config;
+    private readonly fetchImpl;
+    private readonly skewMs;
+    private readonly now;
+    private token;
+    private expiresAt;
+    private inFlight;
+    constructor(config: ClientCredentials, opts?: TokenManagerOptions);
+    /** Return a valid token, fetching/refreshing only when needed. */
+    getToken(): Promise<string>;
+    /** Force a new token regardless of the cached one's validity. */
+    refresh(): Promise<string>;
+    private acquire;
+    private doFetch;
+    private safeBody;
+}
+export {};
+//# sourceMappingURL=tokenManager.d.ts.map

package/dist/auth/tokenManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenManager.d.ts","sourceRoot":"","sources":["../../src/auth/tokenManager.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,mBAAmB;IAC3B,qDAAqD;IACrD,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAQD;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAgC;gBAEpC,MAAM,EAAE,iBAAiB,EAAE,IAAI,GAAE,mBAAwB;IAOrE,kEAAkE;IAC5D,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAOjC,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAKhC,OAAO,CAAC,OAAO;YAQD,OAAO;YAwDP,QAAQ;CAWvB"}

package/dist/auth/tokenManager.js

@@ -0,0 +1,108 @@
+import { ZenAuthError } from "../errors.js";
+/**
+ * Owns the OAuth client_credentials token lifecycle for one client:
+ * acquisition, in-memory caching, proactive skew-based refresh, single
+ * in-flight de-duplication, and forced refresh after a 401.
+ */
+export class TokenManager {
+    config;
+    fetchImpl;
+    skewMs;
+    now;
+    token = null;
+    expiresAt = 0;
+    inFlight = null;
+    constructor(config, opts = {}) {
+        this.config = config;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        this.skewMs = opts.skewMs ?? 30_000;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Return a valid token, fetching/refreshing only when needed. */
+    async getToken() {
+        if (this.token !== null && this.now() < this.expiresAt - this.skewMs) {
+            return this.token;
+        }
+        return this.acquire();
+    }
+    /** Force a new token regardless of the cached one's validity. */
+    async refresh() {
+        this.token = null;
+        return this.acquire();
+    }
+    acquire() {
+        if (this.inFlight)
+            return this.inFlight;
+        this.inFlight = this.doFetch().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    async doFetch() {
+        const body = new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.config.clientId,
+            client_secret: this.config.clientSecret,
+        });
+        if (this.config.scope)
+            body.set("scope", this.config.scope);
+        let response;
+        try {
+            response = await this.fetchImpl(this.config.tokenUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                body,
+            });
+        }
+        catch (cause) {
+            throw new ZenAuthError({
+                message: `Token request to ${this.config.tokenUrl} failed: ${String(cause)}`,
+            });
+        }
+        if (!response.ok) {
+            const errBody = await this.safeBody(response);
+            throw new ZenAuthError({
+                message: `Token request failed with HTTP ${response.status}`,
+                status: response.status,
+                body: errBody,
+            });
+        }
+        let data;
+        try {
+            data = (await response.json());
+        }
+        catch (cause) {
+            throw new ZenAuthError({
+                message: `Token response was not valid JSON: ${String(cause)}`,
+                status: response.status,
+            });
+        }
+        if (!data.access_token || typeof data.expires_in !== "number") {
+            throw new ZenAuthError({
+                message: "Token response missing access_token or expires_in",
+                status: response.status,
+                body: data,
+            });
+        }
+        this.token = data.access_token;
+        this.expiresAt = this.now() + data.expires_in * 1000; // expires_in is seconds; convert to ms
+        return this.token;
+    }
+    async safeBody(response) {
+        try {
+            return await response.clone().json();
+        }
+        catch {
+            try {
+                return await response.text();
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+}
+//# sourceMappingURL=tokenManager.js.map

package/dist/auth/tokenManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenManager.js","sourceRoot":"","sources":["../../src/auth/tokenManager.ts"],"names":[],"mappings":"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"}

package/dist/client/client/client.gen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.gen.d.ts","sourceRoot":"","sources":["../../../src/client/client/client.gen.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAwD,MAAM,gBAAgB,CAAC;AAY3G,eAAO,MAAM,YAAY,GAAI,SAAQ,MAAW,KAAG,MA2SlD,CAAC"}
+{"version":3,"file":"client.gen.d.ts","sourceRoot":"","sources":["../../../src/client/client/client.gen.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAA0C,MAAM,gBAAgB,CAAC;AAY7F,eAAO,MAAM,YAAY,GAAI,SAAQ,MAAW,KAAG,MAqVlD,CAAC"}