@skalpgg/sdk 1.0.0 → 1.3.0

package/dist/esm/index.d.ts

@@ -1,5 +1,6 @@
-import type { CheckoutSession, CheckoutSessionStatus, CreateCheckoutParams, CreateSubscriptionCheckoutParams, HeartbeatParams, Invoice, LicenseVerification, ListSubscriptionsParams, Order, Product, SkalpEvent, Subscription, SubscriptionCheckout, SubscriptionCheckoutStatus, SubscriptionList, VerifyLicenseParams } from './types.js';
+import type { AccessRule, AddAccessRuleParams, AddSerialsParams, AddSerialsResult, AdjustCustomerBalanceParams, AppealFeedbackParams, ChangeSubscriptionPlanParams, CheckoutSession, CheckoutSessionStatus, CoinCheckout, CoinCheckoutStatus, Coupon, CreateCheckoutParams, CreateCoinCheckoutParams, CreateCouponParams, CreateCustomerParams, CreateProductGroupParams, CreateProductParams, CreateStoreCategoryParams, CreateSubscriptionCheckoutParams, CreateUsageChargeParams, Customer, CustomerDetails, CustomerList, Deleted, Feedback, FeedbackList, HeartbeatParams, Invoice, LicenseKeyInfo, LicenseValidation, LicenseVerification, ListAccessRulesParams, ListCustomersParams, ListFeedbackParams, ListOrdersParams, ListProductsParams, ListQueriesParams, ListSerialsParams, ListSubscriptionsParams, Order, OrderKeysReplaced, OrderList, Product, ProductGroup, ProductStock, ReplaceOrderKeysParams, ReplyParams, SerialList, SkalpEvent, StoreCategory, StoreCategoryWithCount, Subscription, SubscriptionCheckout, SubscriptionCheckoutStatus, SubscriptionList, SupportQueryDetails, SupportQueryList, ResetLicenseDevicesParams, UpdateCouponParams, UpdateCustomerParams, UpdateProductGroupParams, UpdateProductParams, UpdateStoreCategoryParams, UsageCharge, ValidateLicenseParams, VerifyLicenseParams } from './types.js';
 export type * from './types.js';
+export declare const VERSION = "1.3.0";
 export interface SkalpOptions {
     apiKey?: string;
     webhookSecret?: string;
@@ -19,35 +20,113 @@ export declare class SkalpError extends Error {
     readonly body: unknown;
     constructor(message: string, status: number, code?: string, body?: unknown);
 }
+export declare class SkalpConnectionError extends Error {
+    constructor(method: string, path: string, cause: unknown);
+}
+export type SignatureFailure = 'stale' | 'invalid';
 export declare class SkalpSignatureError extends Error {
-    constructor(message?: string);
+    readonly reason: SignatureFailure;
+    constructor(reason?: SignatureFailure);
 }
 export declare class Skalp {
     #private;
     constructor(options?: string | SkalpOptions);
     readonly checkout: {
-        create: (params: CreateCheckoutParams) => Promise<CheckoutSession>;
+        create: ({ productId, quantity, customerEmail, metadata, couponCode, returnUrl, customFields }: CreateCheckoutParams) => Promise<CheckoutSession>;
         get: (id: string) => Promise<CheckoutSessionStatus>;
     };
     readonly orders: {
+        list: ({ status, productId, email, createdAfter, createdBefore, updatedSince, limit, offset }?: ListOrdersParams) => Promise<OrderList>;
         get: (id: string) => Promise<Order>;
+        cancel: (id: string) => Promise<Order>;
+        replace: (id: string, { serialIds, values, reason }?: ReplaceOrderKeysParams) => Promise<OrderKeysReplaced>;
     };
     readonly products: {
-        list: () => Promise<Product[]>;
+        list: ({ status }?: ListProductsParams) => Promise<Product[]>;
+        get: (idOrSlug: string) => Promise<Product>;
+        create: (params: CreateProductParams) => Promise<Product>;
+        update: (idOrSlug: string, params: UpdateProductParams) => Promise<Product>;
+        archive: (idOrSlug: string) => Promise<Product>;
+        submit: (idOrSlug: string) => Promise<Product>;
+        stock: (idOrSlug: string) => Promise<ProductStock>;
+        listSerials: (idOrSlug: string, { status, limit, offset }?: ListSerialsParams) => Promise<SerialList>;
+        addSerials: (idOrSlug: string, { serials, text, delimiter }: AddSerialsParams) => Promise<AddSerialsResult>;
+        deleteSerial: (idOrSlug: string, serialId: string) => Promise<Deleted>;
+    };
+    readonly categories: {
+        list: () => Promise<StoreCategoryWithCount[]>;
+        create: ({ name }: CreateStoreCategoryParams) => Promise<StoreCategory>;
+        update: (id: string, { name, sortOrder }: UpdateStoreCategoryParams) => Promise<StoreCategory>;
+        delete: (id: string) => Promise<Deleted>;
+    };
+    readonly groups: {
+        list: () => Promise<ProductGroup[]>;
+        get: (id: string) => Promise<ProductGroup>;
+        create: (params: CreateProductGroupParams) => Promise<ProductGroup>;
+        update: (id: string, params: UpdateProductGroupParams) => Promise<ProductGroup>;
+        delete: (id: string) => Promise<Deleted>;
+    };
+    readonly coupons: {
+        list: () => Promise<Coupon[]>;
+        get: (id: string) => Promise<Coupon>;
+        create: (params: CreateCouponParams) => Promise<Coupon>;
+        update: (id: string, params: UpdateCouponParams) => Promise<Coupon>;
+        delete: (id: string) => Promise<Deleted>;
+    };
+    readonly customers: {
+        list: ({ search, limit, offset }?: ListCustomersParams) => Promise<CustomerList>;
+        get: (id: string) => Promise<CustomerDetails>;
+        create: ({ email, name, note }: CreateCustomerParams) => Promise<Customer>;
+        update: (id: string, { name, note }: UpdateCustomerParams) => Promise<Customer>;
+        delete: (id: string) => Promise<Deleted>;
+        adjustBalance: (id: string, { amount, reason }: AdjustCustomerBalanceParams) => Promise<Customer>;
+    };
+    readonly feedback: {
+        list: ({ productId, rating, limit, offset }?: ListFeedbackParams) => Promise<FeedbackList>;
+        get: (id: string) => Promise<Feedback>;
+        reply: (id: string, { message }: ReplyParams) => Promise<Feedback>;
+        appeal: (id: string, { reason }: AppealFeedbackParams) => Promise<Feedback>;
+    };
+    readonly queries: {
+        list: ({ status, limit, offset }?: ListQueriesParams) => Promise<SupportQueryList>;
+        get: (id: string) => Promise<SupportQueryDetails>;
+        reply: (id: string, { message }: ReplyParams) => Promise<SupportQueryDetails>;
+        close: (id: string) => Promise<SupportQueryDetails>;
+        reopen: (id: string) => Promise<SupportQueryDetails>;
+    };
+    readonly blacklist: {
+        list: ({ type }?: ListAccessRulesParams) => Promise<AccessRule[]>;
+        add: ({ type, value, note }: AddAccessRuleParams) => Promise<AccessRule>;
+        remove: (id: string) => Promise<Deleted>;
+    };
+    readonly whitelist: {
+        list: ({ type }?: ListAccessRulesParams) => Promise<AccessRule[]>;
+        add: ({ type, value, note }: AddAccessRuleParams) => Promise<AccessRule>;
+        remove: (id: string) => Promise<Deleted>;
+    };
+    readonly coins: {
+        createCheckout: ({ steamHex, coins, idempotencyKey, returnUrl }: CreateCoinCheckoutParams) => Promise<CoinCheckout>;
+        getCheckoutStatus: (reference: string) => Promise<CoinCheckoutStatus>;
     };
     readonly subscriptions: {
-        createCheckout: (params: CreateSubscriptionCheckoutParams) => Promise<SubscriptionCheckout>;
+        createCheckout: ({ productId, productSlug, customerEmail, externalRef, metadata, currency, returnUrl, }: CreateSubscriptionCheckoutParams) => Promise<SubscriptionCheckout>;
         getCheckout: (id: string) => Promise<SubscriptionCheckoutStatus>;
-        list: (params?: ListSubscriptionsParams) => Promise<SubscriptionList>;
+        list: ({ externalRef, status, updatedSince, limit, offset }?: ListSubscriptionsParams) => Promise<SubscriptionList>;
         get: (id: string) => Promise<Subscription>;
+        changePlan: (id: string, { productId, productSlug }: ChangeSubscriptionPlanParams) => Promise<Subscription>;
         cancel: (id: string) => Promise<Subscription>;
+        createUsageCharge: (id: string, { amount, currency, description, idempotencyKey, periodStart, periodEnd }: CreateUsageChargeParams) => Promise<UsageCharge>;
         listInvoices: (id: string) => Promise<Invoice[]>;
     };
     readonly licenses: {
-        verify: (params: VerifyLicenseParams) => Promise<LicenseVerification>;
-        heartbeat: (params: HeartbeatParams) => Promise<{
+        verify: ({ licenseKey, serverIp, serverKey, serverPort }: VerifyLicenseParams) => Promise<LicenseVerification>;
+        heartbeat: ({ licenseKey, serverIp }: HeartbeatParams) => Promise<{
             valid: boolean;
         }>;
+        validate: ({ key, productId, hardwareId }: ValidateLicenseParams) => Promise<LicenseValidation>;
+        resetDevices: ({ key, hardwareId }: ResetLicenseDevicesParams) => Promise<{
+            license: LicenseKeyInfo;
+        }>;
     };
     readonly webhooks: {
         verify: (payload: WebhookPayload, signature: SignatureSource, secret?: string) => Promise<boolean>;

package/dist/esm/index.js

@@ -1,5 +1,9 @@
+export const VERSION = '1.3.0';
 const SIGNATURE_HEADER = 'skalp-signature';
 const SIGNATURE_TOLERANCE_SECONDS = 300;
+const USER_AGENT = `skalp-node/${VERSION}`;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RETRY_WAIT_SECONDS = 10;
 export class SkalpError extends Error {
     status;
     code;
@@ -12,15 +16,67 @@ export class SkalpError extends Error {
         this.body = body;
     }
 }
+export class SkalpConnectionError extends Error {
+    constructor(method, path, cause) {
+        super(`Skalp: ${method} ${path}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = 'SkalpConnectionError';
+    }
+}
 export class SkalpSignatureError extends Error {
-    constructor(message = 'Invalid Skalp webhook signature') {
-        super(message);
+    reason;
+    constructor(reason = 'invalid') {
+        super(reason === 'stale'
+            ? 'Skalp: webhook signature is outside the replay window'
+            : 'Skalp: invalid webhook signature');
         this.name = 'SkalpSignatureError';
+        this.reason = reason;
     }
 }
 const env = (name) => globalThis.process?.env?.[name];
 const segment = (id) => encodeURIComponent(id);
-const MAX_RETRY_WAIT_SECONDS = 10;
+const isoDate = (value) => (value instanceof Date ? value.toISOString() : value);
+const optionalDate = (value) => value instanceof Date ? value.toISOString() : value;
+const PRODUCT_FIELDS = [
+    'name',
+    'slug',
+    'description',
+    'shortDescription',
+    'price',
+    'comparePrice',
+    'category',
+    'categoryId',
+    'storeCategoryId',
+    'tags',
+    'images',
+    'videoUrl',
+    'fulfillmentType',
+    'billingInterval',
+    'trialPeriodDays',
+    'dynamicUrl',
+    'licenseDeviceLimit',
+    'licenseDurationDays',
+];
+const COUPON_FIELDS = [
+    'discountType',
+    'discountPercent',
+    'discountAmount',
+    'productIds',
+    'disabledWithVolumeDiscounts',
+    'description',
+    'maxUses',
+    'minPurchaseAmount',
+    'oneTimePerUser',
+];
+const GROUP_FIELDS = ['title', 'productIds', 'description', 'image', 'sortPriority', 'unlisted'];
+function pick(source, keys) {
+    const picked = {};
+    for (const key of keys) {
+        const value = source[key];
+        if (value !== undefined)
+            picked[key] = value;
+    }
+    return picked;
+}
 export class Skalp {
     #apiKey;
     #webhookSecret;
@@ -33,7 +89,7 @@ export class Skalp {
         this.#apiKey = o.apiKey ?? env('SKALP_API_KEY');
         this.#webhookSecret = o.webhookSecret ?? env('SKALP_WEBHOOK_SECRET');
         this.#baseUrl = (o.baseUrl ?? env('SKALP_API_URL') ?? 'https://api.skalp.gg').replace(/\/+$/, '');
-        this.#timeout = o.timeout ?? 30_000;
+        this.#timeout = o.timeout && o.timeout > 0 ? o.timeout : DEFAULT_TIMEOUT_MS;
         this.#maxRetries = o.maxRetries ?? 2;
         this.#fetch = o.fetch ?? ((...args) => fetch(...args));
         if (this.#apiKey && 'window' in globalThis && 'document' in globalThis && !o.dangerouslyAllowBrowser) {
@@ -41,62 +97,198 @@ export class Skalp {
         }
     }
     checkout = {
-        create: (params) => {
-            const { productId, ...rest } = params;
-            return this.#request('POST', '/v1/checkout/sessions', {
-                body: { items: [{ productId, quantity: 1 }], ...rest },
-            });
-        },
+        create: ({ productId, quantity, customerEmail, metadata, couponCode, returnUrl, customFields }) => this.#request('POST', '/v1/checkout/sessions', {
+            body: { items: [{ productId, quantity }], customerEmail, metadata, couponCode, returnUrl, customFields },
+        }),
         get: (id) => this.#request('GET', `/v1/checkout/sessions/${segment(id)}`),
     };
     orders = {
+        list: ({ status, productId, email, createdAfter, createdBefore, updatedSince, limit, offset } = {}) => this.#request('GET', '/v1/orders', {
+            query: {
+                status,
+                productId,
+                email,
+                createdAfter: optionalDate(createdAfter),
+                createdBefore: optionalDate(createdBefore),
+                updatedSince: optionalDate(updatedSince),
+                limit,
+                offset,
+            },
+        }),
         get: (id) => this.#request('GET', `/v1/orders/${segment(id)}`),
+        cancel: (id) => this.#request('POST', `/v1/orders/${segment(id)}/cancel`),
+        replace: (id, { serialIds, values, reason } = {}) => this.#request('POST', `/v1/orders/${segment(id)}/replacement`, {
+            body: { serialIds, values, reason },
+        }),
     };
     products = {
-        list: () => this.#request('GET', '/v1/products'),
+        list: ({ status } = {}) => this.#request('GET', '/v1/products', { query: { status } }),
+        get: (idOrSlug) => this.#request('GET', `/v1/products/${segment(idOrSlug)}`),
+        create: (params) => this.#request('POST', '/v1/products', {
+            body: pick(params, [...PRODUCT_FIELDS, 'productType', 'submit']),
+        }),
+        update: (idOrSlug, params) => this.#request('PATCH', `/v1/products/${segment(idOrSlug)}`, {
+            body: pick(params, [...PRODUCT_FIELDS, 'status']),
+        }),
+        archive: (idOrSlug) => this.#request('DELETE', `/v1/products/${segment(idOrSlug)}`),
+        submit: (idOrSlug) => this.#request('POST', `/v1/products/${segment(idOrSlug)}/submit`),
+        stock: (idOrSlug) => this.#request('GET', `/v1/products/${segment(idOrSlug)}/stock`),
+        listSerials: (idOrSlug, { status, limit, offset } = {}) => this.#request('GET', `/v1/products/${segment(idOrSlug)}/serials`, {
+            query: { status, limit, offset },
+        }),
+        addSerials: (idOrSlug, { serials, text, delimiter }) => this.#request('POST', `/v1/products/${segment(idOrSlug)}/serials`, {
+            body: { serials, text, delimiter },
+        }),
+        deleteSerial: (idOrSlug, serialId) => this.#request('DELETE', `/v1/products/${segment(idOrSlug)}/serials/${segment(serialId)}`),
+    };
+    categories = {
+        list: () => this.#request('GET', '/v1/categories'),
+        create: ({ name }) => this.#request('POST', '/v1/categories', { body: { name } }),
+        update: (id, { name, sortOrder }) => this.#request('PATCH', `/v1/categories/${segment(id)}`, { body: { name, sortOrder } }),
+        delete: (id) => this.#request('DELETE', `/v1/categories/${segment(id)}`),
+    };
+    groups = {
+        list: () => this.#request('GET', '/v1/groups'),
+        get: (id) => this.#request('GET', `/v1/groups/${segment(id)}`),
+        create: (params) => this.#request('POST', '/v1/groups', { body: pick(params, GROUP_FIELDS) }),
+        update: (id, params) => this.#request('PATCH', `/v1/groups/${segment(id)}`, { body: pick(params, GROUP_FIELDS) }),
+        delete: (id) => this.#request('DELETE', `/v1/groups/${segment(id)}`),
+    };
+    coupons = {
+        list: () => this.#request('GET', '/v1/coupons'),
+        get: (id) => this.#request('GET', `/v1/coupons/${segment(id)}`),
+        create: (params) => this.#request('POST', '/v1/coupons', {
+            body: {
+                ...pick(params, [...COUPON_FIELDS, 'code']),
+                validFrom: optionalDate(params.validFrom),
+                validTo: optionalDate(params.validTo),
+            },
+        }),
+        update: (id, params) => this.#request('PATCH', `/v1/coupons/${segment(id)}`, {
+            body: {
+                ...pick(params, [...COUPON_FIELDS, 'isActive']),
+                validFrom: optionalDate(params.validFrom),
+                validTo: optionalDate(params.validTo),
+            },
+        }),
+        delete: (id) => this.#request('DELETE', `/v1/coupons/${segment(id)}`),
+    };
+    customers = {
+        list: ({ search, limit, offset } = {}) => this.#request('GET', '/v1/customers', { query: { search, limit, offset } }),
+        get: (id) => this.#request('GET', `/v1/customers/${segment(id)}`),
+        create: ({ email, name, note }) => this.#request('POST', '/v1/customers', { body: { email, name, note } }),
+        update: (id, { name, note }) => this.#request('PATCH', `/v1/customers/${segment(id)}`, { body: { name, note } }),
+        delete: (id) => this.#request('DELETE', `/v1/customers/${segment(id)}`),
+        adjustBalance: (id, { amount, reason }) => this.#request('POST', `/v1/customers/${segment(id)}/balance`, { body: { amount, reason } }),
+    };
+    feedback = {
+        list: ({ productId, rating, limit, offset } = {}) => this.#request('GET', '/v1/feedback', { query: { productId, rating, limit, offset } }),
+        get: (id) => this.#request('GET', `/v1/feedback/${segment(id)}`),
+        reply: (id, { message }) => this.#request('POST', `/v1/feedback/${segment(id)}/reply`, { body: { message } }),
+        appeal: (id, { reason }) => this.#request('POST', `/v1/feedback/${segment(id)}/appeal`, { body: { reason } }),
+    };
+    queries = {
+        list: ({ status, limit, offset } = {}) => this.#request('GET', '/v1/queries', { query: { status, limit, offset } }),
+        get: (id) => this.#request('GET', `/v1/queries/${segment(id)}`),
+        reply: (id, { message }) => this.#request('POST', `/v1/queries/${segment(id)}/reply`, { body: { message } }),
+        close: (id) => this.#request('POST', `/v1/queries/${segment(id)}/close`),
+        reopen: (id) => this.#request('POST', `/v1/queries/${segment(id)}/reopen`),
+    };
+    blacklist = this.#accessRules('blacklist');
+    whitelist = this.#accessRules('whitelist');
+    #accessRules(list) {
+        return {
+            list: ({ type } = {}) => this.#request('GET', `/v1/${list}`, { query: { type } }),
+            add: ({ type, value, note }) => this.#request('POST', `/v1/${list}`, { body: { type, value, note } }),
+            remove: (id) => this.#request('DELETE', `/v1/${list}/${segment(id)}`),
+        };
+    }
+    coins = {
+        createCheckout: ({ steamHex, coins, idempotencyKey, returnUrl }) => this.#request('POST', '/coins/checkout', {
+            body: { steamHex, coins, idempotencyKey, returnUrl },
+        }),
+        getCheckoutStatus: (reference) => this.#request('GET', `/coins/checkout/${segment(reference)}/status`),
     };
     subscriptions = {
-        createCheckout: (params) => this.#request('POST', '/v1/subscriptions/checkout', { body: params }),
+        createCheckout: ({ productId, productSlug, customerEmail, externalRef, metadata, currency, returnUrl, }) => this.#request('POST', '/v1/subscriptions/checkout', {
+            body: { productId, productSlug, customerEmail, externalRef, metadata, currency, returnUrl },
+        }),
         getCheckout: (id) => this.#request('GET', `/v1/subscriptions/checkout/${segment(id)}`),
-        list: (params = {}) => this.#request('GET', '/v1/subscriptions', {
+        list: ({ externalRef, status, updatedSince, limit, offset } = {}) => this.#request('GET', '/v1/subscriptions', {
             query: {
-                ...params,
-                updatedSince: params.updatedSince instanceof Date ? params.updatedSince.toISOString() : params.updatedSince,
+                externalRef,
+                status,
+                updatedSince: updatedSince instanceof Date ? updatedSince.toISOString() : updatedSince,
+                limit,
+                offset,
             },
         }),
         get: (id) => this.#request('GET', `/v1/subscriptions/${segment(id)}`),
+        changePlan: (id, { productId, productSlug }) => this.#request('POST', `/v1/subscriptions/${segment(id)}/plan`, {
+            body: { productId, productSlug },
+        }),
         cancel: (id) => this.#request('DELETE', `/v1/subscriptions/${segment(id)}`),
+        createUsageCharge: (id, { amount, currency, description, idempotencyKey, periodStart, periodEnd }) => this.#request('POST', `/v1/subscriptions/${segment(id)}/usage-charges`, {
+            body: {
+                amount,
+                currency,
+                description,
+                idempotencyKey,
+                periodStart: isoDate(periodStart),
+                periodEnd: isoDate(periodEnd),
+            },
+        }),
         listInvoices: (id) => this.#request('GET', `/v1/subscriptions/${segment(id)}/invoices`).then((r) => r.data),
     };
     licenses = {
-        verify: (params) => this.#request('POST', '/licenses/verify', { body: params, auth: false }),
-        heartbeat: (params) => this.#request('POST', '/licenses/heartbeat', { body: params, auth: false }),
+        verify: ({ licenseKey, serverIp, serverKey, serverPort }) => this.#request('POST', '/licenses/verify', {
+            body: { licenseKey, serverIp, serverKey, serverPort },
+            auth: false,
+        }),
+        heartbeat: ({ licenseKey, serverIp }) => this.#request('POST', '/licenses/heartbeat', {
+            body: { licenseKey, serverIp },
+            auth: false,
+        }),
+        // Keys sold with the "License key" delivery. Needs the licenses:validate
+        // scope; a key with only that scope may ship inside your app.
+        validate: ({ key, productId, hardwareId }) => this.#request('POST', '/v1/licenses/validate', {
+            body: { key, productId, hardwareId },
+        }),
+        // Frees the machines a key is bound to. Needs licenses:write; call it
+        // from your server only.
+        resetDevices: ({ key, hardwareId }) => this.#request('POST', '/v1/licenses/devices/reset', {
+            body: { key, hardwareId },
+        }),
     };
     webhooks = {
-        verify: async (payload, signature, secret) => {
-            const key = secret ?? this.#webhookSecret;
-            if (!key) {
-                throw new Error('Skalp: missing webhook secret. Pass it as the third argument or set SKALP_WEBHOOK_SECRET.');
-            }
-            const encoder = new TextEncoder();
-            const body = toBytes(payload, encoder);
-            const parsed = parseSignature(readSignature(signature));
-            if (!parsed || Math.abs(Date.now() / 1000 - parsed.timestamp) > SIGNATURE_TOLERANCE_SECONDS)
-                return false;
-            const prefix = encoder.encode(`${parsed.timestamp}.`);
-            const signed = new Uint8Array(prefix.length + body.length);
-            signed.set(prefix);
-            signed.set(body, prefix.length);
-            const hmac = await crypto.subtle.importKey('raw', encoder.encode(key), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
-            return crypto.subtle.verify('HMAC', hmac, parsed.signature, signed);
-        },
+        verify: async (payload, signature, secret) => (await this.#checkSignature(payload, signature, secret)) === undefined,
         constructEvent: async (payload, signature, secret) => {
-            if (!(await this.webhooks.verify(payload, signature, secret)))
-                throw new SkalpSignatureError();
+            const failure = await this.#checkSignature(payload, signature, secret);
+            if (failure)
+                throw new SkalpSignatureError(failure);
             const text = typeof payload === 'string' ? payload : new TextDecoder().decode(payload);
             return JSON.parse(text);
         },
     };
+    async #checkSignature(payload, signature, secret) {
+        const key = secret ?? this.#webhookSecret;
+        if (!key) {
+            throw new Error('Skalp: missing webhook secret. Pass it as the third argument or set SKALP_WEBHOOK_SECRET.');
+        }
+        const encoder = new TextEncoder();
+        const body = toBytes(payload, encoder);
+        const parsed = parseSignature(readSignature(signature));
+        if (!parsed)
+            return 'invalid';
+        if (Math.abs(Date.now() / 1000 - parsed.timestamp) > SIGNATURE_TOLERANCE_SECONDS)
+            return 'stale';
+        const prefix = encoder.encode(`${parsed.timestamp}.`);
+        const signed = new Uint8Array(prefix.length + body.length);
+        signed.set(prefix);
+        signed.set(body, prefix.length);
+        const hmac = await crypto.subtle.importKey('raw', encoder.encode(key), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+        return (await crypto.subtle.verify('HMAC', hmac, parsed.signature, signed)) ? undefined : 'invalid';
+    }
     async #request(method, path, { body, query, auth = true } = {}) {
         if (auth && !this.#apiKey) {
             throw new Error('Skalp: missing API key. Pass it to new Skalp(apiKey) or set SKALP_API_KEY.');
@@ -106,18 +298,24 @@ export class Skalp {
             if (value !== undefined && value !== null)
                 url.searchParams.set(name, String(value));
         }
-        const headers = { accept: 'application/json' };
+        const headers = { accept: 'application/json', 'user-agent': USER_AGENT };
         if (auth)
             headers['x-api-key'] = this.#apiKey;
         if (body !== undefined)
             headers['content-type'] = 'application/json';
         for (let attempt = 0;; attempt++) {
-            const res = await this.#fetch(url, {
-                method,
-                headers,
-                body: body === undefined ? undefined : JSON.stringify(body),
-                signal: AbortSignal.timeout(this.#timeout),
-            });
+            let res;
+            try {
+                res = await this.#fetch(url, {
+                    method,
+                    headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: AbortSignal.timeout(this.#timeout),
+                });
+            }
+            catch (cause) {
+                throw new SkalpConnectionError(method, path, cause);
+            }
             if (res.status === 429 && attempt < this.#maxRetries) {
                 const wait = retryAfterSeconds(res, attempt);
                 if (wait <= MAX_RETRY_WAIT_SECONDS) {
@@ -182,7 +380,7 @@ function retryAfterSeconds(res, attempt) {
     const reset = Number(res.headers.get('x-ratelimit-reset'));
     if (reset > 0)
         return Math.max(reset - Date.now() / 1000, 0.5);
-    return 2 ** attempt;
+    return 2 ** Math.min(attempt, 5);
 }
 function toError(status, body) {
     const b = (body && typeof body === 'object' ? body : {});