@hiclimba/client 0.0.3 → 0.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @hiclimba/client
 
-Toasty API SDK for product backends and customer-scoped integrations.
+Climba API SDK for product backends and customer-scoped integrations.
 
 ```bash
 npm install @hiclimba/client
@@ -8,18 +8,18 @@ npm install @hiclimba/client
 
 ## Server Mode
 
-Server mode uses Toasty app HMAC credentials. Keep it on the product backend.
+Server mode uses Climba app HMAC credentials. Keep it on the product backend.
 
 ```ts
-import { ToastyClient } from '@hiclimba/client';
+import { ClimbaClient } from '@hiclimba/client';
 
-const toasty = new ToastyClient({
+const climba = new ClimbaClient({
   appId: process.env.TOASTY_APP_ID!,
   keyId: process.env.TOASTY_KEY_ID!,
   secret: process.env.TOASTY_SECRET!,
 });
 
-const identified = await toasty.identify({
+const identified = await climba.identify({
   shop: 'merchant.myshopify.com',
   shopifyShopGid: 'gid://shopify/Shop/123',
 });
@@ -28,15 +28,15 @@ const identified = await toasty.identify({
 The default API URL is `https://api.hiclimba.com`. Pass `apiUrl` only when you
 need to target a local, staging, or private API deployment.
 
-`identify()` returns `customerApiToken`. It is a random Toasty app-installation
+`identify()` returns `customerApiToken`. It is a random Climba app-installation
 lookup token. It is not signed, encrypted, expiring, rotatable, privileged app
 auth, or any kind of Shopify token.
 
 If your backend already has a Shopify Admin delegate token for a known
-installation, server mode can push it to Toasty:
+installation, server mode can push it to Climba:
 
 ```ts
-await toasty.pushShopifyAdminDelegateToken({
+await climba.pushShopifyAdminDelegateToken({
   shop: 'merchant.myshopify.com',
   delegateToken: '<shopify-admin-delegate-token>',
   expiresAt: '2026-07-02T12:00:00.000Z',
@@ -44,24 +44,48 @@ await toasty.pushShopifyAdminDelegateToken({
 });
 ```
 
-Toasty validates the token against Shopify with a minimal Admin GraphQL request
+Climba validates the token against Shopify with a minimal Admin GraphQL request
 before storing it encrypted on the existing installation. The pushed token is
 server-side only and must never be sent from browser code.
 
+## Delegate Token Provider Verification
+
+If Climba pulls delegate tokens from your backend, verify those requests with
+the server-only verifier subpath:
+
+```ts
+import { verifyClimbaDelegateTokenProviderRequest } from '@hiclimba/client/delegate-token-provider';
+
+const result = await verifyClimbaDelegateTokenProviderRequest({
+  rawBody,
+  headers,
+  shopifyAppClientSecret: process.env.SHOPIFY_API_SECRET!,
+  expectedAppId: process.env.TOASTY_APP_ID!,
+  consumeReplayKey: async ({ key, ttlSeconds }) => {
+    return await storeReplayKeyOnce(key, ttlSeconds);
+  },
+});
+```
+
+Climba signs the exact raw JSON body bytes with the Shopify app client secret
+using standard Base64 HMAC-SHA256 and sends `x-climba-*` headers. Use the
+signed body timestamp and request ID for freshness and replay checks. The
+headers are mirrored for routing and logging only.
+
 ## Customer Mode
 
-Customer mode uses the Toasty app ID plus the `customerApiToken` returned by
+Customer mode uses the Climba app ID plus the `customerApiToken` returned by
 `identify()`.
 
 ```ts
-const toasty = new ToastyClient({
+const climba = new ClimbaClient({
   appId: '<toasty-app-id>',
   customerApiToken: '<customer-api-token>',
 });
 
-const customer = await toasty.getCustomer();
-const enabled = await toasty.isFeatureEnabled('api_access');
-await toasty.sendUsageEvent({
+const customer = await climba.getCustomer();
+const enabled = await climba.isFeatureEnabled('api_access');
+await climba.sendUsageEvent({
   eventName: 'order_processed',
   idempotencyKey: 'order_123',
 });

package/delegate-token-provider.d.ts

@@ -0,0 +1 @@
+export * from './lib/delegate-token-provider.js';

package/delegate-token-provider.js

@@ -0,0 +1 @@
+export * from './lib/delegate-token-provider.js';

package/index.d.ts

@@ -1,2 +1,2 @@
-export * from './lib/toasty-client.js';
-export type * from './lib/toasty-client.types.js';
+export * from './lib/climba-client.js';
+export type * from './lib/climba-client.types.js';

package/index.js

@@ -1 +1 @@
-export * from './lib/toasty-client.js';
+export * from './lib/climba-client.js';

package/lib/{toasty-client.d.ts → climba-client.d.ts}

@@ -1,4 +1,4 @@
-import type { ICancelSubscriptionInput, ICancelSubscriptionResponse, ICreateOneTimeChargeInput, ICreateOneTimeChargeResponse, ICreateSubscriptionInput, ICreateSubscriptionResponse, IGetCustomerResponse, IGetUsageMetricReportInput, IGetUsageMetricReportResponse, IIdentifyInput, IIdentifyResponse, IPublicCustomerDto, IPublicCustomerFeatureDto, IPublicCustomerPlanDto, IPublicCustomerSubscriptionDto, IPublicCustomerUsageMetricDto, ITrackUsageEventBatchInput, ITrackUsageEventBatchResponse, ITrackUsageEventInput, ITrackUsageEventResponse, IUpdateSubscriptionInput, IUpdateSubscriptionResponse, IPushShopifyAdminDelegateTokenInput, IPushShopifyAdminDelegateTokenResponse, IPlanDiscount } from './toasty-client.types.js';
+import type { ICancelSubscriptionInput, ICancelSubscriptionResponse, ICreateOneTimeChargeInput, ICreateOneTimeChargeResponse, ICreateSubscriptionInput, ICreateSubscriptionResponse, IGetCustomerResponse, IGetUsageMetricReportInput, IGetUsageMetricReportResponse, IIdentifyInput, IIdentifyResponse, IPlanDiscount, IPublicCustomerDto, IPublicCustomerFeatureDto, IPublicCustomerPlanDto, IPublicCustomerSubscriptionDto, IPublicCustomerUsageMetricDto, IPushShopifyAdminDelegateTokenInput, IPushShopifyAdminDelegateTokenResponse, ITrackUsageEventBatchInput, ITrackUsageEventBatchResponse, ITrackUsageEventInput, ITrackUsageEventResponse, IUpdateSubscriptionInput, IUpdateSubscriptionResponse } from './climba-client.types.js';
 export declare const DEFAULT_API_URL = "https://api.hiclimba.com";
 export type Customer = IPublicCustomerDto;
 export type Plan = IPublicCustomerPlanDto;
@@ -10,7 +10,7 @@ export type Discount = IPlanDiscount;
 export type AppliedDiscount = IPlanDiscount;
 export type UsageEvent = ITrackUsageEventResponse;
 export type SubscribeParams = ICreateSubscriptionInput;
-export interface IToastyServerClientConfig {
+export interface IClimbaServerClientConfig {
     appId: string;
     keyId: string;
     secret: string;
@@ -18,14 +18,14 @@ export interface IToastyServerClientConfig {
     fetch?: typeof fetch;
     allowBrowserServerCredentials?: boolean;
 }
-export interface IToastyCustomerClientConfig {
+export interface IClimbaCustomerClientConfig {
     appId: string;
     customerApiToken: string;
     apiUrl?: string;
     fetch?: typeof fetch;
 }
-export type IToastyClientConfig = IToastyServerClientConfig | IToastyCustomerClientConfig;
-export interface ICreateToastyHmacHeadersInput {
+export type IClimbaClientConfig = IClimbaServerClientConfig | IClimbaCustomerClientConfig;
+export interface ICreateClimbaHmacHeadersInput {
     appId: string;
     keyId: string;
     secret: string;
@@ -34,55 +34,55 @@ export interface ICreateToastyHmacHeadersInput {
     timestamp?: string;
     rawBody?: Buffer;
 }
-export interface ICreateToastyHmacHeadersResult {
+export interface ICreateClimbaHmacHeadersResult {
     canonicalString: string;
     headers: Record<string, string>;
 }
-export interface IToastyError {
-    name: 'ToastyError';
+export interface IClimbaError {
+    name: 'ClimbaError';
     status: number;
     code: string;
     message: string;
     responseBody?: unknown;
 }
-export type ToastyError = IToastyError;
-type ToastyResult<T> = Promise<T | ToastyError>;
+export type ClimbaError = IClimbaError;
+type ClimbaResult<T> = Promise<T | ClimbaError>;
 export declare function sha256HexRawBody(rawBody?: Buffer): string;
-export declare function buildToastyHmacCanonicalString(input: {
+export declare function buildClimbaHmacCanonicalString(input: {
     method: string;
     pathWithQuery: string;
     timestamp: string;
     rawBody?: Buffer;
 }): string;
-export declare function deriveToastyCredentialSigningKey(input: {
+export declare function deriveClimbaCredentialSigningKey(input: {
     rawSecret: string;
     appPublicId: string;
     keyId: string;
 }): Buffer;
-export declare function signToastyHmacCanonicalString(canonicalString: string, signingKey: Buffer): string;
-export declare function createToastyHmacHeaders(input: ICreateToastyHmacHeadersInput): ICreateToastyHmacHeadersResult;
+export declare function signClimbaHmacCanonicalString(canonicalString: string, signingKey: Buffer): string;
+export declare function createClimbaHmacHeaders(input: ICreateClimbaHmacHeadersInput): ICreateClimbaHmacHeadersResult;
 export declare function getPathWithQuery(url: URL): string;
-export declare function isToastyError(value: unknown): value is ToastyError;
-export declare class ToastyClient {
+export declare function isClimbaError(value: unknown): value is ClimbaError;
+export declare class ClimbaClient {
     private readonly config;
     private readonly apiUrl;
     private readonly fetchImpl;
-    constructor(config: IToastyClientConfig);
-    identify(input: IIdentifyInput): ToastyResult<IIdentifyResponse>;
-    pushShopifyAdminDelegateToken(input: IPushShopifyAdminDelegateTokenInput): ToastyResult<IPushShopifyAdminDelegateTokenResponse>;
+    constructor(config: IClimbaClientConfig);
+    identify(input: IIdentifyInput): ClimbaResult<IIdentifyResponse>;
+    pushShopifyAdminDelegateToken(input: IPushShopifyAdminDelegateTokenInput): ClimbaResult<IPushShopifyAdminDelegateTokenResponse>;
     getCustomer(input?: {
         customerId?: string;
-    }): ToastyResult<IGetCustomerResponse>;
-    evaluateFeature(featureKey: string): ToastyResult<Feature | null>;
-    isFeatureEnabled(featureKey: string): ToastyResult<boolean>;
-    limitForFeature(featureKey: string): ToastyResult<number | null>;
-    subscribe(input: ICreateSubscriptionInput): ToastyResult<ICreateSubscriptionResponse>;
-    cancelSubscription(input: ICancelSubscriptionInput): ToastyResult<ICancelSubscriptionResponse>;
-    updateSubscription(input: IUpdateSubscriptionInput): ToastyResult<IUpdateSubscriptionResponse>;
-    createOneTimeCharge(input: ICreateOneTimeChargeInput): ToastyResult<ICreateOneTimeChargeResponse>;
-    sendUsageEvent(input: ITrackUsageEventInput): ToastyResult<ITrackUsageEventResponse>;
-    sendUsageEvents(input: ITrackUsageEventBatchInput): ToastyResult<ITrackUsageEventBatchResponse>;
-    getUsageMetricReport(input: IGetUsageMetricReportInput): ToastyResult<IGetUsageMetricReportResponse>;
+    }): ClimbaResult<IGetCustomerResponse>;
+    evaluateFeature(featureKey: string): ClimbaResult<Feature | null>;
+    isFeatureEnabled(featureKey: string): ClimbaResult<boolean>;
+    limitForFeature(featureKey: string): ClimbaResult<number | null>;
+    subscribe(input: ICreateSubscriptionInput): ClimbaResult<ICreateSubscriptionResponse>;
+    cancelSubscription(input: ICancelSubscriptionInput): ClimbaResult<ICancelSubscriptionResponse>;
+    updateSubscription(input: IUpdateSubscriptionInput): ClimbaResult<IUpdateSubscriptionResponse>;
+    createOneTimeCharge(input: ICreateOneTimeChargeInput): ClimbaResult<ICreateOneTimeChargeResponse>;
+    sendUsageEvent(input: ITrackUsageEventInput): ClimbaResult<ITrackUsageEventResponse>;
+    sendUsageEvents(input: ITrackUsageEventBatchInput): ClimbaResult<ITrackUsageEventBatchResponse>;
+    getUsageMetricReport(input: IGetUsageMetricReportInput): ClimbaResult<IGetUsageMetricReportResponse>;
     private get;
     private post;
     private requestJson;

package/lib/{toasty-client.js → climba-client.js}

@@ -7,32 +7,25 @@ export function sha256HexRawBody(rawBody) {
         .update(rawBody ?? Buffer.alloc(0))
         .digest('hex');
 }
-export function buildToastyHmacCanonicalString(input) {
-    return [
-        input.method.toUpperCase(),
-        input.pathWithQuery,
-        input.timestamp,
-        sha256HexRawBody(input.rawBody),
-    ].join('\n');
+export function buildClimbaHmacCanonicalString(input) {
+    return [input.method.toUpperCase(), input.pathWithQuery, input.timestamp, sha256HexRawBody(input.rawBody)].join('\n');
 }
-export function deriveToastyCredentialSigningKey(input) {
+export function deriveClimbaCredentialSigningKey(input) {
     return Buffer.from(hkdfSync('sha256', Buffer.from(input.rawSecret, 'utf8'), Buffer.from(`${input.appPublicId}:${input.keyId}`, 'utf8'), Buffer.from(SIGNING_KEY_INFO, 'utf8'), 32));
 }
-export function signToastyHmacCanonicalString(canonicalString, signingKey) {
-    const digest = createHmac('sha256', signingKey)
-        .update(canonicalString)
-        .digest('hex');
+export function signClimbaHmacCanonicalString(canonicalString, signingKey) {
+    const digest = createHmac('sha256', signingKey).update(canonicalString).digest('hex');
     return `${HMAC_SIGNATURE_PREFIX}${digest}`;
 }
-export function createToastyHmacHeaders(input) {
+export function createClimbaHmacHeaders(input) {
     const timestamp = input.timestamp ?? new Date().toISOString();
-    const canonicalString = buildToastyHmacCanonicalString({
+    const canonicalString = buildClimbaHmacCanonicalString({
         method: input.method,
         pathWithQuery: input.pathWithQuery,
         timestamp,
         ...(input.rawBody ? { rawBody: input.rawBody } : {}),
     });
-    const signingKey = deriveToastyCredentialSigningKey({
+    const signingKey = deriveClimbaCredentialSigningKey({
         rawSecret: input.secret,
         appPublicId: input.appId,
         keyId: input.keyId,
@@ -43,19 +36,17 @@ export function createToastyHmacHeaders(input) {
             'x-toasty-app-id': input.appId,
             'x-toasty-key-id': input.keyId,
             'x-toasty-timestamp': timestamp,
-            'x-toasty-signature': signToastyHmacCanonicalString(canonicalString, signingKey),
+            'x-toasty-signature': signClimbaHmacCanonicalString(canonicalString, signingKey),
         },
     };
 }
 export function getPathWithQuery(url) {
     return `${url.pathname}${url.search}`;
 }
-export function isToastyError(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        value.name === 'ToastyError');
+export function isClimbaError(value) {
+    return typeof value === 'object' && value !== null && value.name === 'ClimbaError';
 }
-export class ToastyClient {
+export class ClimbaClient {
     config;
     apiUrl;
     fetchImpl;
@@ -98,14 +89,14 @@ export class ToastyClient {
     async evaluateFeature(featureKey) {
         assertConfigValue('featureKey', featureKey);
         const response = await this.getCustomer();
-        if (isToastyError(response)) {
+        if (isClimbaError(response)) {
             return response;
         }
         return response.customer.features[featureKey] ?? null;
     }
     async isFeatureEnabled(featureKey) {
         const feature = await this.evaluateFeature(featureKey);
-        if (isToastyError(feature)) {
+        if (isClimbaError(feature)) {
             return feature;
         }
         if (!feature) {
@@ -115,7 +106,7 @@ export class ToastyClient {
     }
     async limitForFeature(featureKey) {
         const feature = await this.evaluateFeature(featureKey);
-        if (isToastyError(feature)) {
+        if (isClimbaError(feature)) {
             return feature;
         }
         if (!feature) {
@@ -169,13 +160,13 @@ export class ToastyClient {
         });
         const responseBody = await readResponseBody(response);
         if (!response.ok) {
-            return toToastyError(response.status, responseBody);
+            return toClimbaError(response.status, responseBody);
         }
         return responseBody;
     }
     createAuthHeaders(method, pathWithQuery, rawBody) {
         if (isServerConfig(this.config)) {
-            return createToastyHmacHeaders({
+            return createClimbaHmacHeaders({
                 appId: this.config.appId,
                 keyId: this.config.keyId,
                 secret: this.config.secret,
@@ -236,17 +227,11 @@ async function readResponseBody(response) {
         return text;
     }
 }
-function toToastyError(status, responseBody) {
-    const body = typeof responseBody === 'object' && responseBody !== null
-        ? responseBody
-        : {};
-    const code = typeof body.error === 'string'
-        ? body.error
-        : typeof body.code === 'string'
-            ? body.code
-            : 'toasty_api_error';
+function toClimbaError(status, responseBody) {
+    const body = typeof responseBody === 'object' && responseBody !== null ? responseBody : {};
+    const code = typeof body.error === 'string' ? body.error : typeof body.code === 'string' ? body.code : 'toasty_api_error';
     return {
-        name: 'ToastyError',
+        name: 'ClimbaError',
         status,
         code,
         message: code,
@@ -254,9 +239,7 @@ function toToastyError(status, responseBody) {
     };
 }
 function isBrowserRuntime() {
-    return (typeof globalThis === 'object' &&
-        'window' in globalThis &&
-        'document' in globalThis);
+    return typeof globalThis === 'object' && 'window' in globalThis && 'document' in globalThis;
 }
 function assertNoShopifyTokenFields(input) {
     const value = input;
@@ -283,8 +266,7 @@ function featureValueEnabled(value) {
     return value.value !== 0;
 }
 function featureLimit(value) {
-    if (value.type === 'limit' ||
-        value.type === 'limit_with_overage') {
+    if (value.type === 'limit' || value.type === 'limit_with_overage') {
         return value.value;
     }
     return null;

package/lib/{toasty-client.types.d.ts → climba-client.types.d.ts}

@@ -95,7 +95,7 @@ export interface IUsageBillingCap {
     cappedAmount: number;
 }
 export type PublicPlanUsageBillingConfig = IUsageBillingConfig;
-export type ToastyBillingStatus = 'none' | 'pending_approval' | 'trialing' | 'active' | 'inactive';
+export type ClimbaBillingStatus = 'none' | 'pending_approval' | 'trialing' | 'active' | 'inactive';
 export interface IPublicCustomerFeatureDto {
     id: string;
     key: string;
@@ -153,7 +153,7 @@ export interface IPublicCustomerDto {
     myshopifyDomain: string;
     displayName?: string;
     shopDomain?: string;
-    billingStatus: ToastyBillingStatus;
+    billingStatus: ClimbaBillingStatus;
     plans: IPublicCustomerPlanDto[];
     subscription: IPublicCustomerSubscriptionDto | null;
     features: Record<string, IPublicCustomerFeatureDto>;

package/lib/delegate-token-provider.d.ts

@@ -0,0 +1,37 @@
+export type ClimbaDelegateTokenProviderHeaderName = 'x-climba-hmac-sha256' | 'x-climba-timestamp' | 'x-climba-request-id' | 'x-climba-app-id';
+export type ClimbaDelegateTokenProviderVerificationFailureCode = 'missing_header' | 'duplicate_header' | 'invalid_hmac' | 'malformed_json' | 'header_body_mismatch' | 'stale_timestamp' | 'replayed_request' | 'invalid_body';
+export interface IClimbaDelegateTokenProviderRequestBody {
+    app_id: string;
+    installation_id: string;
+    customer_id: string;
+    myshopify_domain: string;
+    shopify_shop_gid?: string;
+    timestamp: string;
+    request_id: string;
+}
+export interface IVerifyClimbaDelegateTokenProviderRequestInput {
+    rawBody: Buffer | Uint8Array | string;
+    headers: Headers | Record<string, string | string[] | undefined>;
+    shopifyAppClientSecret: string;
+    expectedAppId?: string;
+    now?: Date;
+    toleranceSeconds?: number;
+    consumeReplayKey?: (input: {
+        key: string;
+        appId: string;
+        requestId: string;
+        ttlSeconds: number;
+    }) => boolean | Promise<boolean>;
+}
+export interface IVerifyClimbaDelegateTokenProviderRequestSuccess {
+    ok: true;
+    body: IClimbaDelegateTokenProviderRequestBody;
+    replayKey: string;
+    replayChecked: boolean;
+}
+export interface IVerifyClimbaDelegateTokenProviderRequestFailure {
+    ok: false;
+    code: ClimbaDelegateTokenProviderVerificationFailureCode;
+}
+export type VerifyClimbaDelegateTokenProviderRequestResult = IVerifyClimbaDelegateTokenProviderRequestSuccess | IVerifyClimbaDelegateTokenProviderRequestFailure;
+export declare function verifyClimbaDelegateTokenProviderRequest(input: IVerifyClimbaDelegateTokenProviderRequestInput): Promise<VerifyClimbaDelegateTokenProviderRequestResult>;

package/lib/delegate-token-provider.js

@@ -0,0 +1,185 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const DEFAULT_TOLERANCE_SECONDS = 300;
+const SIGNATURE_HEADER = 'x-climba-hmac-sha256';
+const TIMESTAMP_HEADER = 'x-climba-timestamp';
+const REQUEST_ID_HEADER = 'x-climba-request-id';
+const APP_ID_HEADER = 'x-climba-app-id';
+const REQUIRED_HEADERS = [
+    SIGNATURE_HEADER,
+    TIMESTAMP_HEADER,
+    REQUEST_ID_HEADER,
+    APP_ID_HEADER,
+];
+export async function verifyClimbaDelegateTokenProviderRequest(input) {
+    const headers = extractRequiredHeaders(input.headers);
+    if (!headers.ok) {
+        return headers;
+    }
+    const rawBodyBytes = normalizeRawBody(input.rawBody);
+    if (!verifyBase64Hmac({
+        rawBodyBytes,
+        providedSignature: headers.values[SIGNATURE_HEADER],
+        shopifyAppClientSecret: input.shopifyAppClientSecret,
+    })) {
+        return { ok: false, code: 'invalid_hmac' };
+    }
+    const parsedBody = parseJsonBody(rawBodyBytes);
+    if (!parsedBody.ok) {
+        return { ok: false, code: 'malformed_json' };
+    }
+    const body = validateBody(parsedBody.value);
+    if (!body) {
+        return { ok: false, code: 'invalid_body' };
+    }
+    if (body.app_id !== headers.values[APP_ID_HEADER] ||
+        body.timestamp !== headers.values[TIMESTAMP_HEADER] ||
+        body.request_id !== headers.values[REQUEST_ID_HEADER]) {
+        return { ok: false, code: 'header_body_mismatch' };
+    }
+    if (input.expectedAppId && body.app_id !== input.expectedAppId) {
+        return { ok: false, code: 'header_body_mismatch' };
+    }
+    if (input.expectedAppId && headers.values[APP_ID_HEADER] !== input.expectedAppId) {
+        return { ok: false, code: 'header_body_mismatch' };
+    }
+    const toleranceSeconds = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (!isFreshTimestamp(body.timestamp, input.now ?? new Date(), toleranceSeconds)) {
+        return { ok: false, code: 'stale_timestamp' };
+    }
+    const replayKey = `${body.app_id}:${body.request_id}`;
+    if (input.consumeReplayKey) {
+        const replayAccepted = await input.consumeReplayKey({
+            key: replayKey,
+            appId: body.app_id,
+            requestId: body.request_id,
+            ttlSeconds: toleranceSeconds,
+        });
+        if (!replayAccepted) {
+            return { ok: false, code: 'replayed_request' };
+        }
+    }
+    return {
+        ok: true,
+        body,
+        replayKey,
+        replayChecked: Boolean(input.consumeReplayKey),
+    };
+}
+function extractRequiredHeaders(headers) {
+    const normalized = new Map();
+    if (isHeaders(headers)) {
+        for (const name of REQUIRED_HEADERS) {
+            const value = headers.get(name);
+            if (value !== null) {
+                normalized.set(name, value);
+            }
+        }
+    }
+    else {
+        for (const [name, value] of Object.entries(headers)) {
+            const lowerName = name.toLowerCase();
+            if (!isRequiredHeader(lowerName) || value === undefined) {
+                continue;
+            }
+            if (normalized.has(lowerName)) {
+                return { ok: false, code: 'duplicate_header' };
+            }
+            normalized.set(lowerName, value);
+        }
+    }
+    const values = {};
+    for (const name of REQUIRED_HEADERS) {
+        const value = normalized.get(name);
+        if (value === undefined) {
+            return { ok: false, code: 'missing_header' };
+        }
+        if (Array.isArray(value) || value.includes(',')) {
+            return { ok: false, code: 'duplicate_header' };
+        }
+        if (!value.trim()) {
+            return { ok: false, code: 'missing_header' };
+        }
+        values[name] = value.trim();
+    }
+    return { ok: true, values };
+}
+function isHeaders(value) {
+    return typeof value.get === 'function';
+}
+function isRequiredHeader(value) {
+    return REQUIRED_HEADERS.includes(value);
+}
+function normalizeRawBody(rawBody) {
+    if (typeof rawBody === 'string') {
+        return Buffer.from(rawBody, 'utf8');
+    }
+    return Buffer.from(rawBody);
+}
+function verifyBase64Hmac(input) {
+    if (!isStandardSha256Base64(input.providedSignature)) {
+        return false;
+    }
+    const expectedSignature = createHmac('sha256', Buffer.from(input.shopifyAppClientSecret, 'utf8'))
+        .update(input.rawBodyBytes)
+        .digest('base64');
+    const expected = Buffer.from(expectedSignature, 'utf8');
+    const provided = Buffer.from(input.providedSignature, 'utf8');
+    return expected.length === provided.length && timingSafeEqual(expected, provided);
+}
+function isStandardSha256Base64(value) {
+    if (!/^[A-Za-z0-9+/]{43}=$/.test(value)) {
+        return false;
+    }
+    try {
+        return Buffer.from(value, 'base64').length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+function parseJsonBody(rawBodyBytes) {
+    try {
+        return { ok: true, value: JSON.parse(rawBodyBytes.toString('utf8')) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function validateBody(parsed) {
+    if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') {
+        return null;
+    }
+    const body = parsed;
+    if (!isNonEmptyString(body.app_id) ||
+        !isNonEmptyString(body.installation_id) ||
+        !isNonEmptyString(body.customer_id) ||
+        !isNonEmptyString(body.myshopify_domain) ||
+        !isNonEmptyString(body.timestamp) ||
+        !isNonEmptyString(body.request_id)) {
+        return null;
+    }
+    if (body.shopify_shop_gid !== undefined &&
+        typeof body.shopify_shop_gid !== 'string') {
+        return null;
+    }
+    return {
+        app_id: body.app_id,
+        installation_id: body.installation_id,
+        customer_id: body.customer_id,
+        myshopify_domain: body.myshopify_domain,
+        ...(body.shopify_shop_gid ? { shopify_shop_gid: body.shopify_shop_gid } : {}),
+        timestamp: body.timestamp,
+        request_id: body.request_id,
+    };
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && Boolean(value.trim());
+}
+function isFreshTimestamp(value, now, toleranceSeconds) {
+    const timestamp = new Date(value);
+    if (Number.isNaN(timestamp.getTime())) {
+        return false;
+    }
+    const differenceMs = Math.abs(now.getTime() - timestamp.getTime());
+    return differenceMs <= toleranceSeconds * 1000;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hiclimba/client",
-  "version": "0.0.3",
-  "description": "Node SDK for Toasty product backends and customer-scoped API access.",
+  "version": "0.0.4",
+  "description": "Node SDK for Climba product backends and customer-scoped API access.",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -14,12 +14,19 @@
       "types": "./index.d.ts",
       "import": "./index.js",
       "default": "./index.js"
+    },
+    "./delegate-token-provider": {
+      "types": "./delegate-token-provider.d.ts",
+      "import": "./delegate-token-provider.js",
+      "default": "./delegate-token-provider.js"
     }
   },
   "sideEffects": false,
   "files": [
     "index.js",
     "index.d.ts",
+    "delegate-token-provider.js",
+    "delegate-token-provider.d.ts",
     "lib/**/*.js",
     "lib/**/*.d.ts",
     "README.md",