@hiclimba/client 0.0.2

package/README.md

@@ -0,0 +1,106 @@
+# @hiclimba/client
+
+Toasty API SDK for product backends and customer-scoped integrations.
+
+```bash
+npm install @hiclimba/client
+```
+
+## Server Mode
+
+Server mode uses Toasty app HMAC credentials. Keep it on the product backend.
+
+```ts
+import { ToastyClient } from '@hiclimba/client';
+
+const toasty = new ToastyClient({
+  appId: process.env.TOASTY_APP_ID!,
+  keyId: process.env.TOASTY_KEY_ID!,
+  secret: process.env.TOASTY_SECRET!,
+  apiUrl: process.env.TOASTY_API_URL!,
+});
+
+const identified = await toasty.identify({
+  shop: 'merchant.myshopify.com',
+  shopifyShopGid: 'gid://shopify/Shop/123',
+});
+```
+
+`identify()` returns `customerApiToken`. It is a random Toasty app-installation
+lookup token. It is not signed, encrypted, expiring, rotatable, privileged app
+auth, or any kind of Shopify token.
+
+## Customer Mode
+
+Customer mode uses the Toasty app ID plus the `customerApiToken` returned by
+`identify()`.
+
+```ts
+const toasty = new ToastyClient({
+  appId: '<toasty-app-id>',
+  customerApiToken: '<customer-api-token>',
+  apiUrl: 'https://api.toasty.dev',
+});
+
+const customer = await toasty.getCustomer();
+const enabled = await toasty.isFeatureEnabled('api_access');
+await toasty.sendUsageEvent({
+  eventName: 'order_processed',
+  idempotencyKey: 'order_123',
+});
+```
+
+Customer mode sends:
+
+```http
+X-Toasty-App-Id: app_...
+Authorization: Bearer custok_...
+```
+
+## Top-Level Methods
+
+- `identify`
+- `getCustomer`
+- `evaluateFeature`
+- `isFeatureEnabled`
+- `limitForFeature`
+- `subscribe`
+- `cancelSubscription`
+- `updateSubscription`
+- `createOneTimeCharge`
+- `sendUsageEvent`
+- `sendUsageEvents`
+- `getUsageMetricReport`
+
+The SDK intentionally has no Mantle-style nested namespaces such as
+`client.usage.*`, `client.subscriptions.*`, or `client.customers.*`.
+
+## Building
+
+Run `npm exec -- nx run toasty-client:build` to build the library.
+
+Run `npm exec -- nx run toasty-client:build:production` to build the local npm
+publish artifact in `packages/toasty/client/dist`.
+
+Run `npm exec -- nx run toasty-client:verify-publish-artifact` before release.
+
+## Running unit tests
+
+Run `npm exec -- nx run toasty-client:test` to execute the unit tests via Jest.
+
+## Publishing
+
+The source package remains private. Npm publishing uses only
+`packages/toasty/client/dist` as the package root.
+
+Dry-run the publish artifact:
+
+```bash
+npm exec -- nx release publish --projects=toasty-client --dry-run --access public
+```
+
+Publish after versioning and verification:
+
+```bash
+npm exec -- nx release publish --projects=toasty-client --access public
+```

package/index.d.ts

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

package/index.js

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

package/lib/toasty-client.d.ts

@@ -0,0 +1,90 @@
+import type { ICancelSubscriptionInput, ICancelSubscriptionResponse, ICreateOneTimeChargeInput, ICreateOneTimeChargeResponse, ICreateSubscriptionInput, ICreateSubscriptionResponse, IGetCustomerResponse, IGetUsageMetricReportInput, IGetUsageMetricReportResponse, IIdentifyInput, IIdentifyResponse, IPublicCustomerDto, IPublicCustomerFeatureDto, IPublicCustomerPlanDto, IPublicCustomerSubscriptionDto, IPublicCustomerUsageMetricDto, ITrackUsageEventBatchInput, ITrackUsageEventBatchResponse, ITrackUsageEventInput, ITrackUsageEventResponse, IUpdateSubscriptionInput, IUpdateSubscriptionResponse, IPlanDiscount } from './toasty-client.types.js';
+export type Customer = IPublicCustomerDto;
+export type Plan = IPublicCustomerPlanDto;
+export type Subscription = IPublicCustomerSubscriptionDto;
+export type Feature = IPublicCustomerFeatureDto;
+export type UsageMetric = IPublicCustomerUsageMetricDto;
+export type UsageCharge = ICreateOneTimeChargeResponse;
+export type Discount = IPlanDiscount;
+export type AppliedDiscount = IPlanDiscount;
+export type UsageEvent = ITrackUsageEventResponse;
+export type SubscribeParams = ICreateSubscriptionInput;
+export interface IToastyServerClientConfig {
+    appId: string;
+    keyId: string;
+    secret: string;
+    apiUrl: string;
+    fetch?: typeof fetch;
+    allowBrowserServerCredentials?: boolean;
+}
+export interface IToastyCustomerClientConfig {
+    appId: string;
+    customerApiToken: string;
+    apiUrl: string;
+    fetch?: typeof fetch;
+}
+export type IToastyClientConfig = IToastyServerClientConfig | IToastyCustomerClientConfig;
+export interface ICreateToastyHmacHeadersInput {
+    appId: string;
+    keyId: string;
+    secret: string;
+    method: string;
+    pathWithQuery: string;
+    timestamp?: string;
+    rawBody?: Buffer;
+}
+export interface ICreateToastyHmacHeadersResult {
+    canonicalString: string;
+    headers: Record<string, string>;
+}
+export interface IToastyError {
+    name: 'ToastyError';
+    status: number;
+    code: string;
+    message: string;
+    responseBody?: unknown;
+}
+export type ToastyError = IToastyError;
+type ToastyResult<T> = Promise<T | ToastyError>;
+export declare function sha256HexRawBody(rawBody?: Buffer): string;
+export declare function buildToastyHmacCanonicalString(input: {
+    method: string;
+    pathWithQuery: string;
+    timestamp: string;
+    rawBody?: Buffer;
+}): string;
+export declare function deriveToastyCredentialSigningKey(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 getPathWithQuery(url: URL): string;
+export declare function isToastyError(value: unknown): value is ToastyError;
+export declare class ToastyClient {
+    private readonly config;
+    private readonly apiUrl;
+    private readonly fetchImpl;
+    constructor(config: IToastyClientConfig);
+    identify(input: IIdentifyInput): ToastyResult<IIdentifyResponse>;
+    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>;
+    private get;
+    private post;
+    private requestJson;
+    private createAuthHeaders;
+    private assertServerMode;
+}
+export {};

package/lib/toasty-client.js

@@ -0,0 +1,285 @@
+import { createHash, createHmac, hkdfSync } from 'node:crypto';
+const HMAC_SIGNATURE_PREFIX = 'v1=';
+const SIGNING_KEY_INFO = 'toasty-hmac-signing-key-v1';
+export function sha256HexRawBody(rawBody) {
+    return createHash('sha256')
+        .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 deriveToastyCredentialSigningKey(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');
+    return `${HMAC_SIGNATURE_PREFIX}${digest}`;
+}
+export function createToastyHmacHeaders(input) {
+    const timestamp = input.timestamp ?? new Date().toISOString();
+    const canonicalString = buildToastyHmacCanonicalString({
+        method: input.method,
+        pathWithQuery: input.pathWithQuery,
+        timestamp,
+        ...(input.rawBody ? { rawBody: input.rawBody } : {}),
+    });
+    const signingKey = deriveToastyCredentialSigningKey({
+        rawSecret: input.secret,
+        appPublicId: input.appId,
+        keyId: input.keyId,
+    });
+    return {
+        canonicalString,
+        headers: {
+            'x-toasty-app-id': input.appId,
+            'x-toasty-key-id': input.keyId,
+            'x-toasty-timestamp': timestamp,
+            'x-toasty-signature': signToastyHmacCanonicalString(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 class ToastyClient {
+    config;
+    apiUrl;
+    fetchImpl;
+    constructor(config) {
+        assertConfigValue('appId', config.appId);
+        assertConfigValue('apiUrl', config.apiUrl);
+        if (isServerConfig(config)) {
+            assertConfigValue('keyId', config.keyId);
+            assertConfigValue('secret', config.secret);
+            if (isBrowserRuntime() && !config.allowBrowserServerCredentials) {
+                throw new TypeError('Server credential mode cannot be used in browser runtimes');
+            }
+        }
+        else {
+            assertConfigValue('customerApiToken', config.customerApiToken);
+        }
+        this.config = config;
+        this.apiUrl = normalizeApiUrl(config.apiUrl);
+        this.fetchImpl = config.fetch ?? fetch;
+    }
+    identify(input) {
+        this.assertServerMode('identify');
+        assertNoShopifyTokenFields(input);
+        return this.post('/v1/identify', input);
+    }
+    getCustomer(input = {}) {
+        if (isServerConfig(this.config)) {
+            if (!input.customerId) {
+                throw new TypeError('customerId is required in server mode');
+            }
+            return this.get(`/v1/customers/${encodeURIComponent(input.customerId)}`);
+        }
+        return this.get('/v1/customer');
+    }
+    async evaluateFeature(featureKey) {
+        assertConfigValue('featureKey', featureKey);
+        const response = await this.getCustomer();
+        if (isToastyError(response)) {
+            return response;
+        }
+        return response.customer.features[featureKey] ?? null;
+    }
+    async isFeatureEnabled(featureKey) {
+        const feature = await this.evaluateFeature(featureKey);
+        if (isToastyError(feature)) {
+            return feature;
+        }
+        if (!feature) {
+            return false;
+        }
+        return featureValueEnabled(feature.value);
+    }
+    async limitForFeature(featureKey) {
+        const feature = await this.evaluateFeature(featureKey);
+        if (isToastyError(feature)) {
+            return feature;
+        }
+        if (!feature) {
+            return null;
+        }
+        return featureLimit(feature.value);
+    }
+    subscribe(input) {
+        return this.post('/v1/subscriptions', input);
+    }
+    cancelSubscription(input) {
+        return this.post('/v1/subscriptions/cancel', input);
+    }
+    updateSubscription(input) {
+        return this.post('/v1/subscriptions/update', input);
+    }
+    createOneTimeCharge(input) {
+        return this.post('/v1/one-time-charges', input);
+    }
+    sendUsageEvent(input) {
+        return this.post('/v1/usage-events', input);
+    }
+    sendUsageEvents(input) {
+        return this.post('/v1/usage-events/batch', input);
+    }
+    getUsageMetricReport(input) {
+        return this.get('/v1/usage-metrics/report', input);
+    }
+    get(path, query) {
+        return this.requestJson('GET', path, query ? { query } : {});
+    }
+    post(path, input) {
+        return this.requestJson('POST', path, {
+            body: JSON.stringify(input),
+        });
+    }
+    async requestJson(method, path, options = {}) {
+        const url = createRequestUrl(this.apiUrl, path, options.query);
+        const rawBody = Buffer.from(options.body ?? '', 'utf8');
+        const headers = {
+            accept: 'application/json',
+            ...this.createAuthHeaders(method, getPathWithQuery(url), rawBody),
+        };
+        if (options.body !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
+        const response = await this.fetchImpl(url.toString(), {
+            method,
+            headers,
+            ...(options.body !== undefined ? { body: options.body } : {}),
+        });
+        const responseBody = await readResponseBody(response);
+        if (!response.ok) {
+            return toToastyError(response.status, responseBody);
+        }
+        return responseBody;
+    }
+    createAuthHeaders(method, pathWithQuery, rawBody) {
+        if (isServerConfig(this.config)) {
+            return createToastyHmacHeaders({
+                appId: this.config.appId,
+                keyId: this.config.keyId,
+                secret: this.config.secret,
+                method,
+                pathWithQuery,
+                rawBody,
+            }).headers;
+        }
+        return {
+            'x-toasty-app-id': this.config.appId,
+            authorization: `Bearer ${this.config.customerApiToken}`,
+        };
+    }
+    assertServerMode(methodName) {
+        if (!isServerConfig(this.config)) {
+            throw new TypeError(`${methodName} requires server credential mode`);
+        }
+    }
+}
+function isServerConfig(config) {
+    return 'keyId' in config || 'secret' in config;
+}
+function assertConfigValue(name, value) {
+    if (!value.trim()) {
+        throw new TypeError(`${name} is required`);
+    }
+}
+function normalizeApiUrl(value) {
+    const url = new URL(value);
+    url.search = '';
+    url.hash = '';
+    url.pathname = url.pathname.replace(/\/+$/g, '');
+    return url.toString();
+}
+function createRequestUrl(apiUrl, path, query) {
+    const url = new URL(apiUrl);
+    const basePath = url.pathname.replace(/\/+$/g, '');
+    url.pathname = `${basePath}${path}`;
+    url.search = '';
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined) {
+                url.searchParams.append(key, String(value));
+            }
+        }
+    }
+    return url;
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        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';
+    return {
+        name: 'ToastyError',
+        status,
+        code,
+        message: code,
+        ...(responseBody !== undefined ? { responseBody } : {}),
+    };
+}
+function isBrowserRuntime() {
+    return (typeof globalThis === 'object' &&
+        'window' in globalThis &&
+        'document' in globalThis);
+}
+function assertNoShopifyTokenFields(input) {
+    const value = input;
+    for (const key of [
+        'accessToken',
+        'refreshToken',
+        'accessTokenExpiresAt',
+        'offlineAccessToken',
+        'shopifyOfflineAccessToken',
+        'shopifyRefreshToken',
+    ]) {
+        if (key in value) {
+            throw new TypeError(`${key} is not accepted by identify`);
+        }
+    }
+}
+function featureValueEnabled(value) {
+    if (value.type === 'boolean') {
+        return value.value;
+    }
+    if (value.type === 'string') {
+        return Boolean(value.value);
+    }
+    return value.value !== 0;
+}
+function featureLimit(value) {
+    if (value.type === 'limit' ||
+        value.type === 'limit_with_overage') {
+        return value.value;
+    }
+    return null;
+}

package/lib/toasty-client.types.d.ts

@@ -0,0 +1,294 @@
+export type CurrencyCode = 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD';
+export type LocaleCode = string;
+export interface ILocalizedText {
+    fallbackLocale: LocaleCode;
+    values: Partial<Record<LocaleCode, string>>;
+}
+export type BillingProvider = 'shopify_billing_api' | 'shopify_app_pricing';
+export type SubscriptionStatus = 'pending_approval' | 'trialing' | 'active' | 'frozen' | 'cancelled' | 'declined' | 'expired' | 'failed';
+export type AppInstallationStatus = 'identified' | 'installed' | 'uninstalled' | 'deactivated' | 'reactivated' | 'frozen' | 'unknown';
+export type FeatureType = 'boolean' | 'limit' | 'limit_with_overage' | 'string';
+export type FeatureValue = {
+    type: 'boolean';
+    value: boolean;
+} | {
+    type: 'limit';
+    value: number;
+} | {
+    type: 'limit_with_overage';
+    value: number;
+    linkedUsageMetricId?: string;
+} | {
+    type: 'string';
+    value: string;
+};
+export type UsageMetricAggregation = 'count_events' | 'sum_event_property';
+export type UsageMetricStatus = 'active' | 'archived';
+export type PlanVisibility = 'public' | 'hidden' | 'custom';
+export type BillingInterval = 'every_30_days' | 'annual';
+export type DiscountType = 'percentage' | 'fixed_amount';
+export type PlanCustomFieldValue = boolean | string | number | Record<string, unknown> | unknown[] | null;
+export type PlanUsagePricingType = 'per_unit' | 'per_unit_with_limits' | 'package' | 'percentage';
+export type UsageRollupFrequency = 'immediate' | 'daily' | 'weekly' | 'monthly';
+export type UsageLimitsPeriod = 'billing_period' | 'calendar_month';
+export type PackagePricingRounding = 'ceil' | 'floor' | 'pro_rata';
+export interface IPlanUsagePricingTier {
+    fromQuantity: number;
+    toQuantity?: number;
+    unitPrice: number;
+}
+export interface IPlanDiscount {
+    type: DiscountType;
+    value: number;
+    duration: {
+        type: 'forever';
+    } | {
+        type: 'once';
+    } | {
+        type: 'repeating';
+        cycleCount: number;
+    };
+    reason?: string;
+}
+export interface IRecurringPricing {
+    amount: number;
+    currency: CurrencyCode;
+    interval: BillingInterval;
+    trialDays?: number;
+    discount?: IPlanDiscount;
+}
+export type PlanUsageBillingPricing = {
+    type: 'per_unit';
+    includedQuantity?: number;
+    unitPrice: number;
+} | {
+    type: 'per_unit_with_limits';
+    tiers?: IPlanUsagePricingTier[];
+    unitPrice?: number;
+    minimumBillableQuantity?: number;
+    maximumBillableQuantity?: number;
+} | {
+    type: 'package';
+    includedQuantity?: number;
+    packageSize: number;
+    packagePrice: number;
+    rounding: PackagePricingRounding;
+} | {
+    type: 'percentage';
+    percentageRate: number;
+    amountPropertyName: string;
+    includedAmount?: number;
+};
+export interface IUsageBillingConfig {
+    handle: string;
+    usageMetricId: string;
+    pricingType: PlanUsagePricingType;
+    terms?: ILocalizedText;
+    currency: CurrencyCode;
+    rollupFrequency: UsageRollupFrequency;
+    usageLimitsPeriod: UsageLimitsPeriod;
+    rollOverPendingUsage: boolean;
+    pricing: PlanUsageBillingPricing;
+    linkedFeatureKey?: string;
+}
+export interface IUsageBillingCap {
+    cappedAmount: number;
+}
+export type PublicPlanUsageBillingConfig = IUsageBillingConfig;
+export type ToastyBillingStatus = 'none' | 'pending_approval' | 'trialing' | 'active' | 'inactive';
+export interface IPublicCustomerFeatureDto {
+    id: string;
+    key: string;
+    name: string;
+    description?: string;
+    type: FeatureType;
+    value: FeatureValue;
+    visibleToCustomers: boolean;
+    linkedUsageMetricId?: string;
+}
+export interface IPublicCustomerUsageMetricDto {
+    id: string;
+    name: string;
+    description?: string;
+    eventName: string;
+    aggregationMode: UsageMetricAggregation;
+    propertyName?: string;
+    status: UsageMetricStatus;
+}
+export interface IPublicCustomerUsageByFeatureDto {
+    featureKey: string;
+    usageMetricId: string;
+    eventName: string;
+    limit: number;
+    used: number;
+    remaining: number | null;
+}
+export interface IPublicCustomerPlanDto {
+    id: string;
+    handle: string;
+    name: string;
+    description?: string;
+    terms?: string;
+    visibility: PlanVisibility;
+    pricing: IRecurringPricing;
+    features: IPublicCustomerFeatureDto[];
+    usageBilling: PublicPlanUsageBillingConfig[];
+    usageBillingCap?: IUsageBillingCap;
+    customFields: Record<string, PlanCustomFieldValue>;
+}
+export interface IPublicCustomerSubscriptionDto {
+    id: string;
+    status: SubscriptionStatus;
+    provider: BillingProvider;
+    planId: string;
+    planHandle: string;
+    currentPeriodStart?: string;
+    currentPeriodEnd?: string;
+    trialEndsAt?: string;
+    cancelAtPeriodEnd?: boolean;
+}
+export interface IPublicCustomerDto {
+    id: string;
+    installationId: string;
+    myshopifyDomain: string;
+    displayName?: string;
+    shopDomain?: string;
+    billingStatus: ToastyBillingStatus;
+    plans: IPublicCustomerPlanDto[];
+    subscription: IPublicCustomerSubscriptionDto | null;
+    features: Record<string, IPublicCustomerFeatureDto>;
+    usageMetrics: IPublicCustomerUsageMetricDto[];
+    usageMetricsByEventName: Record<string, IPublicCustomerUsageMetricDto>;
+    usageByFeatureKey: Record<string, IPublicCustomerUsageByFeatureDto>;
+    customFields: Record<string, unknown>;
+}
+export interface IGetCustomerResponse {
+    customer: IPublicCustomerDto;
+}
+export interface IIdentifyInput {
+    shop: string;
+    shopifyShopGid?: string;
+    shopDomain?: string;
+    shopName?: string;
+    email?: string;
+    countryCode?: string;
+    currencyCode?: CurrencyCode;
+    shopifyPlanName?: string;
+    shopifyPlanDisplayName?: string;
+}
+export interface IIdentifyResponse {
+    customerId: string;
+    installationId: string;
+    installationStatus: AppInstallationStatus;
+    customerApiToken: string;
+    customer: IPublicCustomerDto;
+}
+export interface ICreateSubscriptionInput {
+    shop?: string;
+    returnUrl: string;
+    planId?: string;
+    planHandle?: string;
+    test?: boolean;
+}
+export interface ICreateSubscriptionResponse {
+    subscriptionId: string;
+    status: SubscriptionStatus;
+    provider: BillingProvider;
+    confirmationUrl: string;
+    planId: string;
+}
+export interface ICancelSubscriptionInput {
+    shop?: string;
+    subscriptionId: string;
+    prorate?: boolean;
+}
+export interface ICancelSubscriptionResponse {
+    subscriptionId: string;
+    status: SubscriptionStatus;
+    provider: BillingProvider;
+    planId: string;
+}
+export interface IUpdateSubscriptionInput {
+    shop?: string;
+    subscriptionId: string;
+    lineItemId: string;
+    cappedAmount: number;
+}
+export interface IUpdateSubscriptionResponse {
+    subscriptionId: string;
+    status: SubscriptionStatus;
+    provider: BillingProvider;
+    planId: string;
+    confirmationUrl?: string;
+}
+export interface ICreateOneTimeChargeInput {
+    shop?: string;
+    name: string;
+    amount: number;
+    currency: string;
+    returnUrl: string;
+    test?: boolean;
+}
+export interface ICreateOneTimeChargeResponse {
+    chargeId: string;
+    status: string;
+    confirmationUrl: string;
+    provider: BillingProvider;
+}
+export interface ITrackUsageEventInput {
+    shop?: string;
+    eventName: string;
+    quantity?: number;
+    properties?: Record<string, unknown>;
+    idempotencyKey: string;
+    sourceId?: string;
+    occurredAt?: string;
+}
+export interface ITrackUsageLedgerEntryDto {
+    id: string;
+    status: 'included' | 'pending_charge';
+    usageBillingHandle: string;
+    usageMetricHandle: string;
+    quantity: number;
+    amount: number;
+    currency: CurrencyCode;
+}
+export interface ITrackUsageEventResponse {
+    eventId: string;
+    processingStatus: 'processed' | 'failed';
+    reason?: string;
+    ledgerEntries: ITrackUsageLedgerEntryDto[];
+}
+export interface ITrackUsageEventBatchInput {
+    events: ITrackUsageEventInput[];
+}
+export interface ITrackUsageEventBatchItemError {
+    code: string;
+    message?: string;
+}
+export interface ITrackUsageEventBatchItemResponse {
+    index: number;
+    ok: boolean;
+    result?: ITrackUsageEventResponse;
+    error?: ITrackUsageEventBatchItemError;
+}
+export interface ITrackUsageEventBatchResponse {
+    items: ITrackUsageEventBatchItemResponse[];
+}
+export interface IGetUsageMetricReportInput {
+    shop?: string;
+    usageMetricId?: string;
+    eventName?: string;
+    featureKey?: string;
+    from?: string;
+    to?: string;
+}
+export interface IGetUsageMetricReportResponse {
+    usageMetricId: string;
+    eventName: string;
+    featureKey?: string;
+    from?: string;
+    to?: string;
+    total: number;
+    count: number;
+}

package/lib/toasty-client.types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@hiclimba/client",
+  "version": "0.0.2",
+  "description": "Node SDK for Toasty product backends and customer-scoped API access.",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "README.md",
+    "package.json"
+  ],
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}