@skalpgg/sdk 1.0.0 → 1.1.0

package/README.md

@@ -49,6 +49,7 @@ Create the key on the API keys page of your dashboard. Each key is bound to one
 | `subscriptions.getCheckout(id)` | `checkout:read` |
 | `subscriptions.list({ externalRef?, status?, updatedSince?, limit?, offset? })` | `subscriptions:read` |
 | `subscriptions.get(id)` | `subscriptions:read` |
+| `subscriptions.changePlan(id, { productId \| productSlug })` | `subscriptions:write` |
 | `subscriptions.cancel(id)` | `subscriptions:write` |
 | `subscriptions.listInvoices(id)` | `subscriptions:read` |
 | `licenses.verify({ licenseKey, serverIp, serverKey, serverPort? })` | none |
@@ -76,6 +77,18 @@ A webhook with the default events receives every purchase as both `order.paid` a
 
 ## Errors
 
-API errors throw `SkalpError` with `status`, `code` (for example `STORE_REQUIRED`) and the parsed `body`. A `429` is retried up to `maxRetries` times (default 2) when the limit resets within 10 seconds. An invalid webhook signature throws `SkalpSignatureError`.
+A refusal from the API throws `SkalpError` with `status`, `code` (for example `STORE_REQUIRED`) and the parsed `body`. A network failure or a timeout throws `SkalpConnectionError`, naming the call and keeping the original in `cause`, so the two are easy to tell apart:
+
+```ts
+try {
+  await skalp.orders.get(id)
+} catch (error) {
+  if (error instanceof SkalpError) return reportRefusal(error.code, error.status)
+  if (error instanceof SkalpConnectionError) return retryLater()
+  throw error
+}
+```
+
+A `429` is retried up to `maxRetries` times (default 2) when the limit resets within 10 seconds. `constructEvent` throws `SkalpSignatureError` with `reason: 'stale' | 'invalid'` — `'stale'` means the delivery is outside the 5 minute replay window, `'invalid'` means the bytes or the secret do not match.
 
 The constructor throws if it finds an API key in a browser, so the mistake shows up the first time you run the code rather than after a secret key has shipped to users. Pass `dangerouslyAllowBrowser: true` to override it.

package/dist/cjs/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 { ChangeSubscriptionPlanParams, CheckoutSession, CheckoutSessionStatus, CreateCheckoutParams, CreateSubscriptionCheckoutParams, HeartbeatParams, Invoice, LicenseVerification, ListSubscriptionsParams, Order, Product, SkalpEvent, Subscription, SubscriptionCheckout, SubscriptionCheckoutStatus, SubscriptionList, VerifyLicenseParams } from './types.js';
 export type * from './types.js';
+export declare const VERSION = "1.1.0";
 export interface SkalpOptions {
     apiKey?: string;
     webhookSecret?: string;
@@ -19,14 +20,19 @@ 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, customerEmail, metadata, couponCode, returnUrl }: CreateCheckoutParams) => Promise<CheckoutSession>;
         get: (id: string) => Promise<CheckoutSessionStatus>;
     };
     readonly orders: {
@@ -36,16 +42,17 @@ export declare class Skalp {
         list: () => Promise<Product[]>;
     };
     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>;
         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;
         }>;
     };

package/dist/cjs/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Skalp = exports.SkalpSignatureError = exports.SkalpError = void 0;
+exports.Skalp = exports.SkalpSignatureError = exports.SkalpConnectionError = exports.SkalpError = exports.VERSION = void 0;
+exports.VERSION = '1.1.0';
 const SIGNATURE_HEADER = 'skalp-signature';
 const SIGNATURE_TOLERANCE_SECONDS = 300;
+const USER_AGENT = `skalp-node/${exports.VERSION}`;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RETRY_WAIT_SECONDS = 10;
 class SkalpError extends Error {
     status;
     code;
@@ -16,16 +20,26 @@ class SkalpError extends Error {
     }
 }
 exports.SkalpError = SkalpError;
+class SkalpConnectionError extends Error {
+    constructor(method, path, cause) {
+        super(`Skalp: ${method} ${path}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = 'SkalpConnectionError';
+    }
+}
+exports.SkalpConnectionError = SkalpConnectionError;
 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;
     }
 }
 exports.SkalpSignatureError = SkalpSignatureError;
 const env = (name) => globalThis.process?.env?.[name];
 const segment = (id) => encodeURIComponent(id);
-const MAX_RETRY_WAIT_SECONDS = 10;
 class Skalp {
     #apiKey;
     #webhookSecret;
@@ -38,7 +52,7 @@ 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) {
@@ -46,12 +60,9 @@ class Skalp {
         }
     }
     checkout = {
-        create: (params) => {
-            const { productId, ...rest } = params;
-            return this.#request('POST', '/v1/checkout/sessions', {
-                body: { items: [{ productId, quantity: 1 }], ...rest },
-            });
-        },
+        create: ({ productId, customerEmail, metadata, couponCode, returnUrl }) => this.#request('POST', '/v1/checkout/sessions', {
+            body: { items: [{ productId, quantity: 1 }], customerEmail, metadata, couponCode, returnUrl },
+        }),
         get: (id) => this.#request('GET', `/v1/checkout/sessions/${segment(id)}`),
     };
     orders = {
@@ -61,47 +72,65 @@ class Skalp {
         list: () => this.#request('GET', '/v1/products'),
     };
     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)}`),
         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,
+        }),
     };
     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.');
@@ -111,18 +140,24 @@ 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) {
@@ -188,7 +223,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 : {});

package/dist/cjs/types.d.ts

@@ -101,6 +101,10 @@ export interface Subscription {
     createdAt: string;
     updatedAt: string;
 }
+export interface ChangeSubscriptionPlanParams {
+    productId?: string;
+    productSlug?: string;
+}
 export interface ListSubscriptionsParams {
     externalRef?: string;
     status?: SubscriptionStatus;
@@ -151,7 +155,7 @@ export interface HeartbeatParams {
     licenseKey: string;
     serverIp: string;
 }
-interface Event<TType extends string, TData> {
+interface Envelope<TType extends string, TData> {
     type: TType;
     timestamp: string;
     data: TData;
@@ -194,6 +198,10 @@ export interface OrderRefundedData {
     refundId: string;
     amount: number;
     reason: string | null;
+    identifier: string | null;
+    steamHex: string | null;
+    coins?: number;
+    giftRecipient: boolean;
 }
 export interface OrderDisputedData {
     orderId: string;
@@ -236,17 +244,17 @@ export interface WebhookTestData {
     webhookId: string;
     sample: Partial<OrderPaidData>;
 }
-export type SkalpEvent = Event<'order.paid' | 'purchase.completed', OrderPaidData> | Event<'order.refunded', OrderRefundedData> | Event<'order.disputed' | 'account.suspend', OrderDisputedData> | Event<'account.restore', AccountRestoreData> | Event<'subscription.created' | 'subscription.updated', SubscriptionEventData> | Event<'subscription.renewed', SubscriptionEventData & {
+export type SkalpEvent = Envelope<'order.paid' | 'purchase.completed', OrderPaidData> | Envelope<'order.refunded', OrderRefundedData> | Envelope<'order.disputed' | 'account.suspend', OrderDisputedData> | Envelope<'account.restore', AccountRestoreData> | Envelope<'subscription.created' | 'subscription.updated', SubscriptionEventData> | Envelope<'subscription.renewed', SubscriptionEventData & {
     invoiceId: string;
     amountPaid: number;
     periodExtendedTo: string;
-}> | Event<'subscription.past_due', SubscriptionEventData & {
+}> | Envelope<'subscription.past_due', SubscriptionEventData & {
     invoiceId: string;
     attemptCount: number;
     nextPaymentAttempt: string | null;
-}> | Event<'subscription.canceled', SubscriptionEventData & {
+}> | Envelope<'subscription.canceled', SubscriptionEventData & {
     endedAt: string | null;
     cancelReason: 'requested' | 'payment_failure' | 'stripe';
-}> | Event<'webhook.test', WebhookTestData>;
+}> | Envelope<'webhook.test', WebhookTestData>;
 export type SkalpEventType = SkalpEvent['type'];
 export {};

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 { ChangeSubscriptionPlanParams, CheckoutSession, CheckoutSessionStatus, CreateCheckoutParams, CreateSubscriptionCheckoutParams, HeartbeatParams, Invoice, LicenseVerification, ListSubscriptionsParams, Order, Product, SkalpEvent, Subscription, SubscriptionCheckout, SubscriptionCheckoutStatus, SubscriptionList, VerifyLicenseParams } from './types.js';
 export type * from './types.js';
+export declare const VERSION = "1.1.0";
 export interface SkalpOptions {
     apiKey?: string;
     webhookSecret?: string;
@@ -19,14 +20,19 @@ 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, customerEmail, metadata, couponCode, returnUrl }: CreateCheckoutParams) => Promise<CheckoutSession>;
         get: (id: string) => Promise<CheckoutSessionStatus>;
     };
     readonly orders: {
@@ -36,16 +42,17 @@ export declare class Skalp {
         list: () => Promise<Product[]>;
     };
     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>;
         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;
         }>;
     };

package/dist/esm/index.js

@@ -1,5 +1,9 @@
+export const VERSION = '1.1.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,24 @@ 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;
 export class Skalp {
     #apiKey;
     #webhookSecret;
@@ -33,7 +46,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,12 +54,9 @@ 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, customerEmail, metadata, couponCode, returnUrl }) => this.#request('POST', '/v1/checkout/sessions', {
+            body: { items: [{ productId, quantity: 1 }], customerEmail, metadata, couponCode, returnUrl },
+        }),
         get: (id) => this.#request('GET', `/v1/checkout/sessions/${segment(id)}`),
     };
     orders = {
@@ -56,47 +66,65 @@ export class Skalp {
         list: () => this.#request('GET', '/v1/products'),
     };
     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)}`),
         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,
+        }),
     };
     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 +134,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 +216,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 : {});

package/dist/esm/types.d.ts

@@ -101,6 +101,10 @@ export interface Subscription {
     createdAt: string;
     updatedAt: string;
 }
+export interface ChangeSubscriptionPlanParams {
+    productId?: string;
+    productSlug?: string;
+}
 export interface ListSubscriptionsParams {
     externalRef?: string;
     status?: SubscriptionStatus;
@@ -151,7 +155,7 @@ export interface HeartbeatParams {
     licenseKey: string;
     serverIp: string;
 }
-interface Event<TType extends string, TData> {
+interface Envelope<TType extends string, TData> {
     type: TType;
     timestamp: string;
     data: TData;
@@ -194,6 +198,10 @@ export interface OrderRefundedData {
     refundId: string;
     amount: number;
     reason: string | null;
+    identifier: string | null;
+    steamHex: string | null;
+    coins?: number;
+    giftRecipient: boolean;
 }
 export interface OrderDisputedData {
     orderId: string;
@@ -236,17 +244,17 @@ export interface WebhookTestData {
     webhookId: string;
     sample: Partial<OrderPaidData>;
 }
-export type SkalpEvent = Event<'order.paid' | 'purchase.completed', OrderPaidData> | Event<'order.refunded', OrderRefundedData> | Event<'order.disputed' | 'account.suspend', OrderDisputedData> | Event<'account.restore', AccountRestoreData> | Event<'subscription.created' | 'subscription.updated', SubscriptionEventData> | Event<'subscription.renewed', SubscriptionEventData & {
+export type SkalpEvent = Envelope<'order.paid' | 'purchase.completed', OrderPaidData> | Envelope<'order.refunded', OrderRefundedData> | Envelope<'order.disputed' | 'account.suspend', OrderDisputedData> | Envelope<'account.restore', AccountRestoreData> | Envelope<'subscription.created' | 'subscription.updated', SubscriptionEventData> | Envelope<'subscription.renewed', SubscriptionEventData & {
     invoiceId: string;
     amountPaid: number;
     periodExtendedTo: string;
-}> | Event<'subscription.past_due', SubscriptionEventData & {
+}> | Envelope<'subscription.past_due', SubscriptionEventData & {
     invoiceId: string;
     attemptCount: number;
     nextPaymentAttempt: string | null;
-}> | Event<'subscription.canceled', SubscriptionEventData & {
+}> | Envelope<'subscription.canceled', SubscriptionEventData & {
     endedAt: string | null;
     cancelReason: 'requested' | 'payment_failure' | 'stripe';
-}> | Event<'webhook.test', WebhookTestData>;
+}> | Envelope<'webhook.test', WebhookTestData>;
 export type SkalpEventType = SkalpEvent['type'];
 export {};

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@skalpgg/sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Official Skalp SDK for Node.js and edge runtimes: checkout, subscriptions, webhooks and license verification.",
   "license": "MIT",
-  "publishConfig": { "access": "public" },
   "homepage": "https://skalp.gg/docs/sdk",
+  "bugs": {
+    "url": "https://skalp.gg/contact"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "skalp",
     "payments",