@skalpgg/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SDN Ventures LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# skalp
+
+The official Skalp SDK for Node.js and edge runtimes: hosted checkout, subscriptions, webhook verification and license checks, with types for every response.
+
+Full documentation with Next.js, Express, NestJS, Hono and Fastify examples: https://skalp.gg/docs/sdk
+
+```sh
+npm install @skalpgg/sdk
+```
+
+Runs on Node 20+, Bun, Deno, Vercel Edge and Cloudflare Workers. No dependencies; ships ESM, CommonJS and types.
+
+## Quickstart
+
+```sh
+SKALP_API_KEY=sk_live_xxx
+SKALP_WEBHOOK_SECRET=your_webhook_secret
+```
+
+```ts
+import { Skalp } from '@skalpgg/sdk'
+
+const skalp = new Skalp()
+
+const session = await skalp.checkout.create({
+  productId: 'prod_xxx',
+  customerEmail: 'buyer@example.com',
+  returnUrl: 'https://example.com/thanks',
+})
+
+console.log(session.url)
+```
+
+Send the buyer to `session.url`, then confirm the payment from the `order.paid` webhook.
+
+`new Skalp()` reads `SKALP_API_KEY` and `SKALP_WEBHOOK_SECRET`. You can also pass them in: `new Skalp('sk_live_xxx')` or `new Skalp({ apiKey, webhookSecret, baseUrl, timeout, maxRetries, fetch })`.
+
+Create the key on the API keys page of your dashboard. Each key is bound to one store.
+
+## Methods
+
+| Method | Scope |
+| --- | --- |
+| `checkout.create({ productId, customerEmail?, metadata?, couponCode?, returnUrl? })` | `checkout:write` |
+| `checkout.get(id)` | `checkout:read` |
+| `orders.get(id)` | `orders:read` |
+| `products.list()` | `products:read` |
+| `subscriptions.createCheckout({ productId \| productSlug, externalRef?, customerEmail?, currency?, ... })` | `checkout:write` |
+| `subscriptions.getCheckout(id)` | `checkout:read` |
+| `subscriptions.list({ externalRef?, status?, updatedSince?, limit?, offset? })` | `subscriptions:read` |
+| `subscriptions.get(id)` | `subscriptions:read` |
+| `subscriptions.cancel(id)` | `subscriptions:write` |
+| `subscriptions.listInvoices(id)` | `subscriptions:read` |
+| `licenses.verify({ licenseKey, serverIp, serverKey, serverPort? })` | none |
+| `licenses.heartbeat({ licenseKey, serverIp })` | none |
+| `webhooks.constructEvent(rawBody, headers)` | none |
+| `webhooks.verify(rawBody, headers)` | none |
+
+## Webhooks
+
+Pass the raw request body, not parsed JSON, together with the request headers. `constructEvent` checks the `Skalp-Signature` header, an HMAC-SHA256 over the timestamp and the exact bytes Skalp sent, and rejects deliveries older than 5 minutes.
+
+```ts
+export async function POST(request: Request) {
+  const event = await skalp.webhooks.constructEvent(await request.text(), request.headers).catch(() => null)
+  if (!event) return new Response('Invalid signature', { status: 400 })
+
+  if (event.type === 'order.paid') {
+    await grantAccess(event.data.buyerEmail, event.data.licenses ?? [])
+  }
+  return new Response(null, { status: 200 })
+}
+```
+
+A webhook with the default events receives every purchase as both `order.paid` and its legacy name `purchase.completed`. Handle `order.paid` and deduplicate on `data.idempotencyKey`.
+
+## 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`.
+
+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

@@ -0,0 +1,57 @@
+import type { 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 interface SkalpOptions {
+    apiKey?: string;
+    webhookSecret?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    fetch?: typeof fetch;
+    dangerouslyAllowBrowser?: boolean;
+}
+export type WebhookPayload = string | Uint8Array | ArrayBuffer;
+export type SignatureSource = string | null | undefined | {
+    get(name: string): string | null;
+} | Record<string, string | Array<string> | undefined>;
+export declare class SkalpError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly body: unknown;
+    constructor(message: string, status: number, code?: string, body?: unknown);
+}
+export declare class SkalpSignatureError extends Error {
+    constructor(message?: string);
+}
+export declare class Skalp {
+    #private;
+    constructor(options?: string | SkalpOptions);
+    readonly checkout: {
+        create: (params: CreateCheckoutParams) => Promise<CheckoutSession>;
+        get: (id: string) => Promise<CheckoutSessionStatus>;
+    };
+    readonly orders: {
+        get: (id: string) => Promise<Order>;
+    };
+    readonly products: {
+        list: () => Promise<Product[]>;
+    };
+    readonly subscriptions: {
+        createCheckout: (params: CreateSubscriptionCheckoutParams) => Promise<SubscriptionCheckout>;
+        getCheckout: (id: string) => Promise<SubscriptionCheckoutStatus>;
+        list: (params?: ListSubscriptionsParams) => Promise<SubscriptionList>;
+        get: (id: string) => Promise<Subscription>;
+        cancel: (id: string) => Promise<Subscription>;
+        listInvoices: (id: string) => Promise<Invoice[]>;
+    };
+    readonly licenses: {
+        verify: (params: VerifyLicenseParams) => Promise<LicenseVerification>;
+        heartbeat: (params: HeartbeatParams) => Promise<{
+            valid: boolean;
+        }>;
+    };
+    readonly webhooks: {
+        verify: (payload: WebhookPayload, signature: SignatureSource, secret?: string) => Promise<boolean>;
+        constructEvent: (payload: WebhookPayload, signature: SignatureSource, secret?: string) => Promise<SkalpEvent>;
+    };
+}
+export default Skalp;

package/dist/cjs/index.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Skalp = exports.SkalpSignatureError = exports.SkalpError = void 0;
+const SIGNATURE_HEADER = 'skalp-signature';
+const SIGNATURE_TOLERANCE_SECONDS = 300;
+class SkalpError extends Error {
+    status;
+    code;
+    body;
+    constructor(message, status, code, body) {
+        super(message);
+        this.name = 'SkalpError';
+        this.status = status;
+        this.code = code;
+        this.body = body;
+    }
+}
+exports.SkalpError = SkalpError;
+class SkalpSignatureError extends Error {
+    constructor(message = 'Invalid Skalp webhook signature') {
+        super(message);
+        this.name = 'SkalpSignatureError';
+    }
+}
+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;
+    #baseUrl;
+    #timeout;
+    #maxRetries;
+    #fetch;
+    constructor(options = {}) {
+        const o = typeof options === 'string' ? { apiKey: options } : options;
+        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.#maxRetries = o.maxRetries ?? 2;
+        this.#fetch = o.fetch ?? ((...args) => fetch(...args));
+        if (this.#apiKey && 'window' in globalThis && 'document' in globalThis && !o.dangerouslyAllowBrowser) {
+            throw new Error('Skalp: your API key is a secret and must never reach the browser. Call the SDK from server code, or pass dangerouslyAllowBrowser: true if you really know what you are doing.');
+        }
+    }
+    checkout = {
+        create: (params) => {
+            const { productId, ...rest } = params;
+            return this.#request('POST', '/v1/checkout/sessions', {
+                body: { items: [{ productId, quantity: 1 }], ...rest },
+            });
+        },
+        get: (id) => this.#request('GET', `/v1/checkout/sessions/${segment(id)}`),
+    };
+    orders = {
+        get: (id) => this.#request('GET', `/v1/orders/${segment(id)}`),
+    };
+    products = {
+        list: () => this.#request('GET', '/v1/products'),
+    };
+    subscriptions = {
+        createCheckout: (params) => this.#request('POST', '/v1/subscriptions/checkout', { body: params }),
+        getCheckout: (id) => this.#request('GET', `/v1/subscriptions/checkout/${segment(id)}`),
+        list: (params = {}) => this.#request('GET', '/v1/subscriptions', {
+            query: {
+                ...params,
+                updatedSince: params.updatedSince instanceof Date ? params.updatedSince.toISOString() : params.updatedSince,
+            },
+        }),
+        get: (id) => this.#request('GET', `/v1/subscriptions/${segment(id)}`),
+        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 }),
+    };
+    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);
+        },
+        constructEvent: async (payload, signature, secret) => {
+            if (!(await this.webhooks.verify(payload, signature, secret)))
+                throw new SkalpSignatureError();
+            const text = typeof payload === 'string' ? payload : new TextDecoder().decode(payload);
+            return JSON.parse(text);
+        },
+    };
+    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.');
+        }
+        const url = new URL(this.#baseUrl + path);
+        for (const [name, value] of Object.entries(query ?? {})) {
+            if (value !== undefined && value !== null)
+                url.searchParams.set(name, String(value));
+        }
+        const headers = { accept: 'application/json' };
+        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),
+            });
+            if (res.status === 429 && attempt < this.#maxRetries) {
+                const wait = retryAfterSeconds(res, attempt);
+                if (wait <= MAX_RETRY_WAIT_SECONDS) {
+                    await res.body?.cancel();
+                    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
+                    continue;
+                }
+            }
+            const text = await res.text();
+            let data = undefined;
+            try {
+                data = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                data = text;
+            }
+            if (!res.ok)
+                throw toError(res.status, data);
+            return data;
+        }
+    }
+}
+exports.Skalp = Skalp;
+function readSignature(source) {
+    if (source == null || typeof source === 'string')
+        return source ?? undefined;
+    if (typeof source.get === 'function')
+        return source.get(SIGNATURE_HEADER) ?? undefined;
+    const record = source;
+    const value = record[SIGNATURE_HEADER] ?? record['Skalp-Signature'];
+    return Array.isArray(value) ? value[0] : value;
+}
+function parseSignature(header) {
+    let timestamp = NaN;
+    let hex = '';
+    for (const part of header?.split(',') ?? []) {
+        const [name, value = ''] = part.trim().split('=');
+        if (name === 't' && /^\d+$/.test(value))
+            timestamp = Number(value);
+        if (name === 'v1')
+            hex = value;
+    }
+    if (!Number.isSafeInteger(timestamp) || !/^[0-9a-f]{64}$/i.test(hex))
+        return undefined;
+    const signature = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        signature[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return { timestamp, signature };
+}
+function toBytes(payload, encoder) {
+    if (typeof payload === 'string')
+        return encoder.encode(payload);
+    if (payload instanceof ArrayBuffer)
+        return new Uint8Array(payload);
+    if (payload instanceof Uint8Array)
+        return payload;
+    throw new TypeError('Skalp: webhook payload must be the raw request body (string, Buffer or ArrayBuffer). A parsed JSON object cannot be verified, because re-serializing it changes the bytes that were signed.');
+}
+function retryAfterSeconds(res, attempt) {
+    const retryAfter = Number(res.headers.get('retry-after'));
+    if (retryAfter > 0)
+        return retryAfter;
+    const reset = Number(res.headers.get('x-ratelimit-reset'));
+    if (reset > 0)
+        return Math.max(reset - Date.now() / 1000, 0.5);
+    return 2 ** attempt;
+}
+function toError(status, body) {
+    const b = (body && typeof body === 'object' ? body : {});
+    let message = typeof b.message === 'string' ? b.message : typeof body === 'string' && body ? body.slice(0, 200) : '';
+    if (message.startsWith('{')) {
+        try {
+            const inner = JSON.parse(message);
+            if (Array.isArray(inner.message))
+                message = inner.message.join('; ');
+        }
+        catch { }
+    }
+    const code = typeof b.code === 'string' ? b.code : undefined;
+    return new SkalpError(message || `Skalp API responded with ${status}`, status, code, body);
+}
+exports.default = Skalp;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/types.d.ts

@@ -0,0 +1,252 @@
+export type Currency = 'EUR' | 'USD' | 'PLN' | (string & {});
+export type FulfillmentType = 'FILE' | 'SERIAL' | 'GAME' | 'SERVICE';
+export type ProductType = 'ONE_TIME' | 'RECURRING' | 'COINS';
+export type BillingInterval = 'WEEK' | 'MONTH' | 'YEAR';
+export type OrderStatus = 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'REFUNDED' | 'DISPUTED';
+export type SubscriptionStatus = 'ACTIVE' | 'CANCELED' | 'PAST_DUE' | 'UNPAID' | 'INCOMPLETE' | 'INCOMPLETE_EXPIRED' | 'TRIALING' | 'PAUSED';
+export type Metadata = Record<string, string>;
+export interface CreateCheckoutParams {
+    productId: string;
+    customerEmail?: string;
+    metadata?: Metadata;
+    couponCode?: string;
+    returnUrl?: string;
+}
+export interface CheckoutSession {
+    id: string;
+    url: string;
+    expiresAt: string;
+    status: 'pending';
+}
+export interface CheckoutSessionStatus {
+    id: string;
+    status: 'pending' | 'completed' | 'failed';
+    orderNumber: string;
+    amount: number;
+    currency: Currency;
+    completedAt: string | null;
+    metadata: Metadata;
+}
+export interface Order {
+    id: string;
+    orderNumber: string;
+    status: OrderStatus;
+    amount: number;
+    netAmount: number | null;
+    vatAmount: number | null;
+    currency: Currency;
+    productId: string;
+    productName: string;
+    productSlug: string;
+    fulfillmentType: FulfillmentType;
+    buyerEmail: string;
+    serialsCount?: number;
+    createdAt: string;
+    completedAt: string | null;
+    metadata: Metadata;
+}
+export interface Product {
+    id: string;
+    name: string;
+    slug: string;
+    price: number;
+    currency: Currency;
+    fulfillmentType: FulfillmentType;
+    productType: ProductType;
+    billingInterval: BillingInterval | null;
+    trialPeriodDays: number;
+    stock?: number;
+}
+export interface CreateSubscriptionCheckoutParams {
+    productId?: string;
+    productSlug?: string;
+    customerEmail?: string;
+    externalRef?: string;
+    metadata?: Metadata;
+    currency?: 'EUR' | 'USD' | 'PLN';
+    returnUrl?: string;
+}
+export interface SubscriptionCheckout {
+    id: string;
+    url: string;
+    expiresAt: string;
+    status: 'pending';
+}
+export interface SubscriptionCheckoutStatus {
+    id: string;
+    status: 'pending' | 'completed' | 'expired';
+    subscriptionId: string | null;
+    externalRef: string | null;
+    expiresAt: string;
+    metadata: Metadata;
+}
+export interface Subscription {
+    id: string;
+    status: SubscriptionStatus;
+    active: boolean;
+    externalRef: string | null;
+    productId: string;
+    productSlug: string;
+    productName: string;
+    billingInterval: BillingInterval;
+    amount: number;
+    currency: Currency;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    canceledAt: string | null;
+    trialEnd: string | null;
+    buyerEmail: string;
+    metadata: Metadata;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ListSubscriptionsParams {
+    externalRef?: string;
+    status?: SubscriptionStatus;
+    updatedSince?: string | Date;
+    limit?: number;
+    offset?: number;
+}
+export interface SubscriptionList {
+    data: Array<Subscription>;
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface Invoice {
+    id: string;
+    number: string | null;
+    issuedAt: string;
+    dueAt: string | null;
+    total: number;
+    currency: Currency;
+    status: string | null;
+    hostedUrl: string | null;
+    pdfUrl: string | null;
+}
+export interface VerifyLicenseParams {
+    licenseKey: string;
+    serverIp: string;
+    serverKey: string;
+    serverPort?: number;
+}
+export type LicenseError = 'INVALID_FORMAT' | 'INVALID_LICENSE' | 'LICENSE_INACTIVE' | 'LICENSE_EXPIRED' | 'PRODUCT_INACTIVE' | 'SERVER_NOT_ACTIVATED' | 'SERVER_KEY_REQUIRED' | 'SERVER_KEY_MISMATCH' | 'RATE_LIMITED' | 'REPLAY_DETECTED' | (string & {});
+export interface LicenseVerification {
+    valid: boolean;
+    error?: LicenseError;
+    message?: string;
+    activatedServers?: Array<string>;
+    license?: {
+        key: string;
+        product: string;
+        version: string | null;
+        expiresAt: string | null;
+    };
+    token?: string;
+    expiresAt?: string;
+    publicKey?: string;
+}
+export interface HeartbeatParams {
+    licenseKey: string;
+    serverIp: string;
+}
+interface Event<TType extends string, TData> {
+    type: TType;
+    timestamp: string;
+    data: TData;
+}
+export interface WebhookLicense {
+    licenseId: string;
+    licenseKey: string;
+    productId: string;
+    productSlug: string;
+    productName: string;
+}
+export interface OrderPaidData {
+    orderId: string;
+    orderNumber: string;
+    productId: string;
+    productName: string;
+    productSlug: string;
+    buyerId: string;
+    buyerEmail: string;
+    licenseId: string;
+    licenseKey: string;
+    licenses?: Array<WebhookLicense>;
+    serials?: Array<string>;
+    amount: number;
+    currency: Currency;
+    quantity: number;
+    coins?: number;
+    baseCoins?: number;
+    bonusCoins?: number;
+    idempotencyKey: string;
+    steamhex: string | null;
+    identifier: string | null;
+    metadata: Metadata;
+    deliveryType?: string;
+    deliveryCommand?: string;
+}
+export interface OrderRefundedData {
+    orderId: string;
+    orderNumber: string;
+    refundId: string;
+    amount: number;
+    reason: string | null;
+}
+export interface OrderDisputedData {
+    orderId: string;
+    orderNumber: string;
+    disputeId: string;
+    reason: string;
+    steamHex: string | null;
+    identifier: string | null;
+    coins?: number;
+    banned: boolean;
+}
+export interface AccountRestoreData {
+    identifier: string;
+    steamHex: string;
+    reason: string;
+}
+export interface SubscriptionEventData {
+    subscriptionId: string;
+    externalRef: string | null;
+    status: SubscriptionStatus;
+    active: boolean;
+    storeId: string;
+    productId: string;
+    productSlug: string;
+    productName: string;
+    buyerId: string;
+    billingInterval: BillingInterval;
+    amount: number;
+    currency: Currency;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    canceledAt: string | null;
+    trialEnd: string | null;
+    metadata: Metadata;
+    idempotencyKey: string;
+}
+export interface WebhookTestData {
+    message: string;
+    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 & {
+    invoiceId: string;
+    amountPaid: number;
+    periodExtendedTo: string;
+}> | Event<'subscription.past_due', SubscriptionEventData & {
+    invoiceId: string;
+    attemptCount: number;
+    nextPaymentAttempt: string | null;
+}> | Event<'subscription.canceled', SubscriptionEventData & {
+    endedAt: string | null;
+    cancelReason: 'requested' | 'payment_failure' | 'stripe';
+}> | Event<'webhook.test', WebhookTestData>;
+export type SkalpEventType = SkalpEvent['type'];
+export {};

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/index.d.ts

@@ -0,0 +1,57 @@
+import type { 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 interface SkalpOptions {
+    apiKey?: string;
+    webhookSecret?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    fetch?: typeof fetch;
+    dangerouslyAllowBrowser?: boolean;
+}
+export type WebhookPayload = string | Uint8Array | ArrayBuffer;
+export type SignatureSource = string | null | undefined | {
+    get(name: string): string | null;
+} | Record<string, string | Array<string> | undefined>;
+export declare class SkalpError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly body: unknown;
+    constructor(message: string, status: number, code?: string, body?: unknown);
+}
+export declare class SkalpSignatureError extends Error {
+    constructor(message?: string);
+}
+export declare class Skalp {
+    #private;
+    constructor(options?: string | SkalpOptions);
+    readonly checkout: {
+        create: (params: CreateCheckoutParams) => Promise<CheckoutSession>;
+        get: (id: string) => Promise<CheckoutSessionStatus>;
+    };
+    readonly orders: {
+        get: (id: string) => Promise<Order>;
+    };
+    readonly products: {
+        list: () => Promise<Product[]>;
+    };
+    readonly subscriptions: {
+        createCheckout: (params: CreateSubscriptionCheckoutParams) => Promise<SubscriptionCheckout>;
+        getCheckout: (id: string) => Promise<SubscriptionCheckoutStatus>;
+        list: (params?: ListSubscriptionsParams) => Promise<SubscriptionList>;
+        get: (id: string) => Promise<Subscription>;
+        cancel: (id: string) => Promise<Subscription>;
+        listInvoices: (id: string) => Promise<Invoice[]>;
+    };
+    readonly licenses: {
+        verify: (params: VerifyLicenseParams) => Promise<LicenseVerification>;
+        heartbeat: (params: HeartbeatParams) => Promise<{
+            valid: boolean;
+        }>;
+    };
+    readonly webhooks: {
+        verify: (payload: WebhookPayload, signature: SignatureSource, secret?: string) => Promise<boolean>;
+        constructEvent: (payload: WebhookPayload, signature: SignatureSource, secret?: string) => Promise<SkalpEvent>;
+    };
+}
+export default Skalp;

package/dist/esm/index.js

@@ -0,0 +1,201 @@
+const SIGNATURE_HEADER = 'skalp-signature';
+const SIGNATURE_TOLERANCE_SECONDS = 300;
+export class SkalpError extends Error {
+    status;
+    code;
+    body;
+    constructor(message, status, code, body) {
+        super(message);
+        this.name = 'SkalpError';
+        this.status = status;
+        this.code = code;
+        this.body = body;
+    }
+}
+export class SkalpSignatureError extends Error {
+    constructor(message = 'Invalid Skalp webhook signature') {
+        super(message);
+        this.name = 'SkalpSignatureError';
+    }
+}
+const env = (name) => globalThis.process?.env?.[name];
+const segment = (id) => encodeURIComponent(id);
+const MAX_RETRY_WAIT_SECONDS = 10;
+export class Skalp {
+    #apiKey;
+    #webhookSecret;
+    #baseUrl;
+    #timeout;
+    #maxRetries;
+    #fetch;
+    constructor(options = {}) {
+        const o = typeof options === 'string' ? { apiKey: options } : options;
+        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.#maxRetries = o.maxRetries ?? 2;
+        this.#fetch = o.fetch ?? ((...args) => fetch(...args));
+        if (this.#apiKey && 'window' in globalThis && 'document' in globalThis && !o.dangerouslyAllowBrowser) {
+            throw new Error('Skalp: your API key is a secret and must never reach the browser. Call the SDK from server code, or pass dangerouslyAllowBrowser: true if you really know what you are doing.');
+        }
+    }
+    checkout = {
+        create: (params) => {
+            const { productId, ...rest } = params;
+            return this.#request('POST', '/v1/checkout/sessions', {
+                body: { items: [{ productId, quantity: 1 }], ...rest },
+            });
+        },
+        get: (id) => this.#request('GET', `/v1/checkout/sessions/${segment(id)}`),
+    };
+    orders = {
+        get: (id) => this.#request('GET', `/v1/orders/${segment(id)}`),
+    };
+    products = {
+        list: () => this.#request('GET', '/v1/products'),
+    };
+    subscriptions = {
+        createCheckout: (params) => this.#request('POST', '/v1/subscriptions/checkout', { body: params }),
+        getCheckout: (id) => this.#request('GET', `/v1/subscriptions/checkout/${segment(id)}`),
+        list: (params = {}) => this.#request('GET', '/v1/subscriptions', {
+            query: {
+                ...params,
+                updatedSince: params.updatedSince instanceof Date ? params.updatedSince.toISOString() : params.updatedSince,
+            },
+        }),
+        get: (id) => this.#request('GET', `/v1/subscriptions/${segment(id)}`),
+        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 }),
+    };
+    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);
+        },
+        constructEvent: async (payload, signature, secret) => {
+            if (!(await this.webhooks.verify(payload, signature, secret)))
+                throw new SkalpSignatureError();
+            const text = typeof payload === 'string' ? payload : new TextDecoder().decode(payload);
+            return JSON.parse(text);
+        },
+    };
+    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.');
+        }
+        const url = new URL(this.#baseUrl + path);
+        for (const [name, value] of Object.entries(query ?? {})) {
+            if (value !== undefined && value !== null)
+                url.searchParams.set(name, String(value));
+        }
+        const headers = { accept: 'application/json' };
+        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),
+            });
+            if (res.status === 429 && attempt < this.#maxRetries) {
+                const wait = retryAfterSeconds(res, attempt);
+                if (wait <= MAX_RETRY_WAIT_SECONDS) {
+                    await res.body?.cancel();
+                    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
+                    continue;
+                }
+            }
+            const text = await res.text();
+            let data = undefined;
+            try {
+                data = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                data = text;
+            }
+            if (!res.ok)
+                throw toError(res.status, data);
+            return data;
+        }
+    }
+}
+function readSignature(source) {
+    if (source == null || typeof source === 'string')
+        return source ?? undefined;
+    if (typeof source.get === 'function')
+        return source.get(SIGNATURE_HEADER) ?? undefined;
+    const record = source;
+    const value = record[SIGNATURE_HEADER] ?? record['Skalp-Signature'];
+    return Array.isArray(value) ? value[0] : value;
+}
+function parseSignature(header) {
+    let timestamp = NaN;
+    let hex = '';
+    for (const part of header?.split(',') ?? []) {
+        const [name, value = ''] = part.trim().split('=');
+        if (name === 't' && /^\d+$/.test(value))
+            timestamp = Number(value);
+        if (name === 'v1')
+            hex = value;
+    }
+    if (!Number.isSafeInteger(timestamp) || !/^[0-9a-f]{64}$/i.test(hex))
+        return undefined;
+    const signature = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        signature[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return { timestamp, signature };
+}
+function toBytes(payload, encoder) {
+    if (typeof payload === 'string')
+        return encoder.encode(payload);
+    if (payload instanceof ArrayBuffer)
+        return new Uint8Array(payload);
+    if (payload instanceof Uint8Array)
+        return payload;
+    throw new TypeError('Skalp: webhook payload must be the raw request body (string, Buffer or ArrayBuffer). A parsed JSON object cannot be verified, because re-serializing it changes the bytes that were signed.');
+}
+function retryAfterSeconds(res, attempt) {
+    const retryAfter = Number(res.headers.get('retry-after'));
+    if (retryAfter > 0)
+        return retryAfter;
+    const reset = Number(res.headers.get('x-ratelimit-reset'));
+    if (reset > 0)
+        return Math.max(reset - Date.now() / 1000, 0.5);
+    return 2 ** attempt;
+}
+function toError(status, body) {
+    const b = (body && typeof body === 'object' ? body : {});
+    let message = typeof b.message === 'string' ? b.message : typeof body === 'string' && body ? body.slice(0, 200) : '';
+    if (message.startsWith('{')) {
+        try {
+            const inner = JSON.parse(message);
+            if (Array.isArray(inner.message))
+                message = inner.message.join('; ');
+        }
+        catch { }
+    }
+    const code = typeof b.code === 'string' ? b.code : undefined;
+    return new SkalpError(message || `Skalp API responded with ${status}`, status, code, body);
+}
+export default Skalp;

package/dist/esm/types.d.ts

@@ -0,0 +1,252 @@
+export type Currency = 'EUR' | 'USD' | 'PLN' | (string & {});
+export type FulfillmentType = 'FILE' | 'SERIAL' | 'GAME' | 'SERVICE';
+export type ProductType = 'ONE_TIME' | 'RECURRING' | 'COINS';
+export type BillingInterval = 'WEEK' | 'MONTH' | 'YEAR';
+export type OrderStatus = 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'REFUNDED' | 'DISPUTED';
+export type SubscriptionStatus = 'ACTIVE' | 'CANCELED' | 'PAST_DUE' | 'UNPAID' | 'INCOMPLETE' | 'INCOMPLETE_EXPIRED' | 'TRIALING' | 'PAUSED';
+export type Metadata = Record<string, string>;
+export interface CreateCheckoutParams {
+    productId: string;
+    customerEmail?: string;
+    metadata?: Metadata;
+    couponCode?: string;
+    returnUrl?: string;
+}
+export interface CheckoutSession {
+    id: string;
+    url: string;
+    expiresAt: string;
+    status: 'pending';
+}
+export interface CheckoutSessionStatus {
+    id: string;
+    status: 'pending' | 'completed' | 'failed';
+    orderNumber: string;
+    amount: number;
+    currency: Currency;
+    completedAt: string | null;
+    metadata: Metadata;
+}
+export interface Order {
+    id: string;
+    orderNumber: string;
+    status: OrderStatus;
+    amount: number;
+    netAmount: number | null;
+    vatAmount: number | null;
+    currency: Currency;
+    productId: string;
+    productName: string;
+    productSlug: string;
+    fulfillmentType: FulfillmentType;
+    buyerEmail: string;
+    serialsCount?: number;
+    createdAt: string;
+    completedAt: string | null;
+    metadata: Metadata;
+}
+export interface Product {
+    id: string;
+    name: string;
+    slug: string;
+    price: number;
+    currency: Currency;
+    fulfillmentType: FulfillmentType;
+    productType: ProductType;
+    billingInterval: BillingInterval | null;
+    trialPeriodDays: number;
+    stock?: number;
+}
+export interface CreateSubscriptionCheckoutParams {
+    productId?: string;
+    productSlug?: string;
+    customerEmail?: string;
+    externalRef?: string;
+    metadata?: Metadata;
+    currency?: 'EUR' | 'USD' | 'PLN';
+    returnUrl?: string;
+}
+export interface SubscriptionCheckout {
+    id: string;
+    url: string;
+    expiresAt: string;
+    status: 'pending';
+}
+export interface SubscriptionCheckoutStatus {
+    id: string;
+    status: 'pending' | 'completed' | 'expired';
+    subscriptionId: string | null;
+    externalRef: string | null;
+    expiresAt: string;
+    metadata: Metadata;
+}
+export interface Subscription {
+    id: string;
+    status: SubscriptionStatus;
+    active: boolean;
+    externalRef: string | null;
+    productId: string;
+    productSlug: string;
+    productName: string;
+    billingInterval: BillingInterval;
+    amount: number;
+    currency: Currency;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    canceledAt: string | null;
+    trialEnd: string | null;
+    buyerEmail: string;
+    metadata: Metadata;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ListSubscriptionsParams {
+    externalRef?: string;
+    status?: SubscriptionStatus;
+    updatedSince?: string | Date;
+    limit?: number;
+    offset?: number;
+}
+export interface SubscriptionList {
+    data: Array<Subscription>;
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface Invoice {
+    id: string;
+    number: string | null;
+    issuedAt: string;
+    dueAt: string | null;
+    total: number;
+    currency: Currency;
+    status: string | null;
+    hostedUrl: string | null;
+    pdfUrl: string | null;
+}
+export interface VerifyLicenseParams {
+    licenseKey: string;
+    serverIp: string;
+    serverKey: string;
+    serverPort?: number;
+}
+export type LicenseError = 'INVALID_FORMAT' | 'INVALID_LICENSE' | 'LICENSE_INACTIVE' | 'LICENSE_EXPIRED' | 'PRODUCT_INACTIVE' | 'SERVER_NOT_ACTIVATED' | 'SERVER_KEY_REQUIRED' | 'SERVER_KEY_MISMATCH' | 'RATE_LIMITED' | 'REPLAY_DETECTED' | (string & {});
+export interface LicenseVerification {
+    valid: boolean;
+    error?: LicenseError;
+    message?: string;
+    activatedServers?: Array<string>;
+    license?: {
+        key: string;
+        product: string;
+        version: string | null;
+        expiresAt: string | null;
+    };
+    token?: string;
+    expiresAt?: string;
+    publicKey?: string;
+}
+export interface HeartbeatParams {
+    licenseKey: string;
+    serverIp: string;
+}
+interface Event<TType extends string, TData> {
+    type: TType;
+    timestamp: string;
+    data: TData;
+}
+export interface WebhookLicense {
+    licenseId: string;
+    licenseKey: string;
+    productId: string;
+    productSlug: string;
+    productName: string;
+}
+export interface OrderPaidData {
+    orderId: string;
+    orderNumber: string;
+    productId: string;
+    productName: string;
+    productSlug: string;
+    buyerId: string;
+    buyerEmail: string;
+    licenseId: string;
+    licenseKey: string;
+    licenses?: Array<WebhookLicense>;
+    serials?: Array<string>;
+    amount: number;
+    currency: Currency;
+    quantity: number;
+    coins?: number;
+    baseCoins?: number;
+    bonusCoins?: number;
+    idempotencyKey: string;
+    steamhex: string | null;
+    identifier: string | null;
+    metadata: Metadata;
+    deliveryType?: string;
+    deliveryCommand?: string;
+}
+export interface OrderRefundedData {
+    orderId: string;
+    orderNumber: string;
+    refundId: string;
+    amount: number;
+    reason: string | null;
+}
+export interface OrderDisputedData {
+    orderId: string;
+    orderNumber: string;
+    disputeId: string;
+    reason: string;
+    steamHex: string | null;
+    identifier: string | null;
+    coins?: number;
+    banned: boolean;
+}
+export interface AccountRestoreData {
+    identifier: string;
+    steamHex: string;
+    reason: string;
+}
+export interface SubscriptionEventData {
+    subscriptionId: string;
+    externalRef: string | null;
+    status: SubscriptionStatus;
+    active: boolean;
+    storeId: string;
+    productId: string;
+    productSlug: string;
+    productName: string;
+    buyerId: string;
+    billingInterval: BillingInterval;
+    amount: number;
+    currency: Currency;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    canceledAt: string | null;
+    trialEnd: string | null;
+    metadata: Metadata;
+    idempotencyKey: string;
+}
+export interface WebhookTestData {
+    message: string;
+    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 & {
+    invoiceId: string;
+    amountPaid: number;
+    periodExtendedTo: string;
+}> | Event<'subscription.past_due', SubscriptionEventData & {
+    invoiceId: string;
+    attemptCount: number;
+    nextPaymentAttempt: string | null;
+}> | Event<'subscription.canceled', SubscriptionEventData & {
+    endedAt: string | null;
+    cancelReason: 'requested' | 'payment_failure' | 'stripe';
+}> | Event<'webhook.test', WebhookTestData>;
+export type SkalpEventType = SkalpEvent['type'];
+export {};

package/dist/esm/types.js

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

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@skalpgg/sdk",
+  "version": "1.0.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",
+  "keywords": [
+    "skalp",
+    "payments",
+    "checkout",
+    "subscriptions",
+    "webhooks",
+    "licensing",
+    "sdk"
+  ],
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc && tsc --module commonjs --moduleResolution bundler --outDir dist/cjs && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
+}