@skalpgg/sdk 1.3.0 → 1.4.0

package/README.md

@@ -65,13 +65,12 @@ Create the key on the API keys page of your dashboard. Each key is bound to one
 | `coupons.create({ code, discountType?, discountPercent?, discountAmount?, validFrom?, validTo?, maxUses?, ... })` / `coupons.update(id, { ... })` / `coupons.delete(id)` | `coupons:write` |
 | `customers.list({ search?, limit?, offset? })` / `customers.get(id)` | `customers:read` |
 | `customers.create({ email, name?, note? })` / `customers.update(id, { name?, note? })` / `customers.delete(id)` | `customers:write` |
-| `customers.adjustBalance(id, { amount, reason? })` | `customers:write` |
 | `feedback.list({ productId?, rating?, limit?, offset? })` / `feedback.get(id)` | `feedback:read` |
 | `feedback.reply(id, { message })` / `feedback.appeal(id, { reason })` | `feedback:write` |
 | `queries.list({ status?, limit?, offset? })` / `queries.get(id)` | `queries:read` |
 | `queries.reply(id, { message })` / `queries.close(id)` / `queries.reopen(id)` | `queries:write` |
-| `blacklist.list({ type? })` / `whitelist.list({ type? })` | `blacklist:read` |
-| `blacklist.add({ type, value, note? })` / `whitelist.add({ ... })` / `blacklist.remove(id)` / `whitelist.remove(id)` | `blacklist:write` |
+| `blacklist.list({ type? })` / `blacklist.add({ type, value, note? })` / `blacklist.remove(id)` | `blacklist:read` / `blacklist:write` |
+| `whitelist.list({ type? })` / `whitelist.add({ type, value, note? })` / `whitelist.remove(id)` | `whitelist:read` / `whitelist:write` |
 | `subscriptions.createCheckout({ productId \| productSlug, externalRef?, customerEmail?, currency?, ... })` | `checkout:write` |
 | `subscriptions.getCheckout(id)` | `checkout:read` |
 | `subscriptions.list({ externalRef?, status?, updatedSince?, limit?, offset? })` | `subscriptions:read` |
@@ -119,19 +118,17 @@ const { data: orders } = await skalp.orders.list({ status: 'COMPLETED', updatedS
 await skalp.orders.cancel(order.id)
 
 const { replacements } = await skalp.orders.replace(order.id, { reason: 'Key does not activate' })
-
-await skalp.customers.adjustBalance(customer.id, { amount: 10, reason: 'Goodwill credit' })
 ```
 
-`cancel` works only on a `PENDING` order and returns it as `CANCELED`. `replace` swaps the delivered keys of a completed order: with no `serialIds` it replaces every key, and with no `values` it draws the new ones from stock (`values` is required for keys that come from your server). The replacement keys come back in `replacements[].value`. `orders.get` also returns `serialsReplaced` and the `replacements` history.
+`cancel` works only on a `PENDING` order and returns it as `CANCELED`. `replace` swaps the delivered keys of a completed order: with no `serialIds` it replaces every key, and with no `values` it draws the new ones from stock (`values` is required for keys that come from your server). The replacement keys come back in `replacements[].value`. `orders.get` also returns `serialsReplaced`, the `replacements` history and `serials`: the id, status, `deliveredAt` and `replacedById` of every delivered or replaced key (never its value), which are the ids `serialIds` expects.
 
-`updatedSince` lists oldest change first, so you can page through it and keep the last `updatedAt` as your cursor; without it, newest orders come first. Amounts are in major units (`19.5`), balances cannot go below zero, and a customer with a balance cannot be deleted.
+`updatedSince` lists oldest change first, so you can page through it and keep the last `updatedAt` as your cursor; without it, newest orders come first. Amounts are in major units (`19.5`).
 
 Coupons take `validFrom`, `validTo` as an ISO string or a `Date`; `coupons.update` accepts `null` to clear `validTo`, `maxUses`, `minPurchaseAmount` and `description`.
 
 ## Support and access rules
 
-`feedback` and `queries` expose product reviews and buyer conversations. `queries.reply`, `close` and `reopen` return the whole conversation with its `messages`. `blacklist` and `whitelist` use the same calls and the same `blacklist:read` and `blacklist:write` scopes; a whitelisted buyer is never blocked by a blacklist rule.
+`feedback` and `queries` expose product reviews and buyer conversations. `queries.reply`, `close` and `reopen` return the whole conversation with its `messages`. `blacklist` and `whitelist` use the same calls, each with its own read and write scope; a whitelisted buyer is never blocked by a blacklist rule.
 
 ```ts
 await skalp.blacklist.add({ type: 'EMAIL', value: 'chargeback@example.com', note: 'Disputed order 1042' })
@@ -174,7 +171,7 @@ export async function POST(request: Request) {
 
 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`.
 
-`order.created`, `order.updated`, `order.canceled`, `order.replaced`, `query.created`, `query.replied`, `feedback.received` and the subscription events `subscription.updated`, `subscription.trial_started`, `subscription.trial_ended` and `subscription.upcoming` are not in the default list either: subscribe the webhook to them by name, and `event.type` narrows `event.data` to the right payload. `order.created`, `order.updated` and `order.canceled` carry the order as `orders.get` returns it, plus `previousStatus`; `order.replaced` adds `reason` and the new keys in `replacements[].key`. The three trial and upcoming events are accepted by the API but the backend does not send them yet.
+`order.created`, `order.updated`, `order.canceled`, `order.replaced`, `query.created`, `query.replied`, `feedback.received` and the subscription events `subscription.updated`, `subscription.trial_started`, `subscription.trial_ended` and `subscription.upcoming` are not in the default list either: subscribe the webhook to them by name, and `event.type` narrows `event.data` to the right payload. `order.created`, `order.updated` and `order.canceled` carry the order as `orders.get` returns it, plus `previousStatus`; `order.replaced` adds `reason` and the new keys in `replacements[].key`. Every one of them, like `query.created`, `query.replied` and `feedback.received`, carries a `data.idempotencyKey` that stays the same on every retry of the same event, so deduplicate on it. The three trial and upcoming events are accepted by the API but the backend does not send them yet.
 
 `product.created`, `product.updated` and `product.stock` are not in the default list: subscribe the webhook to them by name. `product.stock` carries `stock`, `previousStock` and `change` whenever the number of available keys changes.
 

package/dist/cjs/index.d.ts

@@ -1,6 +1,6 @@
-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';
+import type { AccessRule, AddAccessRuleParams, AddSerialsParams, AddSerialsResult, 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 declare const VERSION = "1.4.0";
 export interface SkalpOptions {
     apiKey?: string;
     webhookSecret?: string;
@@ -79,7 +79,6 @@ export declare class Skalp {
         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>;

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Skalp = exports.SkalpSignatureError = exports.SkalpConnectionError = exports.SkalpError = exports.VERSION = void 0;
-exports.VERSION = '1.3.0';
+exports.VERSION = '1.4.0';
 const SIGNATURE_HEADER = 'skalp-signature';
 const SIGNATURE_TOLERANCE_SECONDS = 300;
 const USER_AGENT = `skalp-node/${exports.VERSION}`;
@@ -185,7 +185,6 @@ class Skalp {
         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 } }),

package/dist/cjs/types.d.ts

@@ -60,6 +60,8 @@ export interface Order {
     deliveryStatus: DeliveryStatus | null;
     serialsCount?: number;
     serialsReplaced?: number;
+    /** Delivered and replaced keys by id, never their values. Only orders.get and orders.cancel fill it in. */
+    serials?: Array<OrderSerial>;
     createdAt: string;
     updatedAt: string;
     completedAt: string | null;
@@ -68,6 +70,14 @@ export interface Order {
     items?: Array<OrderItem>;
     replacements?: Array<OrderReplacement>;
 }
+export interface OrderSerial {
+    id: string;
+    productId: string;
+    status: 'DELIVERED' | 'REPLACED';
+    deliveredAt: string | null;
+    /** The serial that took this one's place, once replaced. */
+    replacedById: string | null;
+}
 export interface OrderReplacement {
     id: string;
     productId: string;
@@ -427,7 +437,6 @@ export interface Customer {
     name: string | null;
     note: string | null;
     country: string | null;
-    balance: number;
     ordersCount: number;
     totalSpent: number;
     currency: Currency;
@@ -436,17 +445,8 @@ export interface Customer {
     createdAt: string;
     updatedAt: string;
 }
-export interface CustomerBalanceEntry {
-    id: string;
-    amount: number;
-    balanceAfter: number;
-    reason: string | null;
-    orderId: string | null;
-    createdAt: string;
-}
 export interface CustomerDetails extends Customer {
     recentOrders: Array<Order>;
-    balanceHistory: Array<CustomerBalanceEntry>;
 }
 export interface ListCustomersParams {
     search?: string;
@@ -468,10 +468,6 @@ export interface UpdateCustomerParams {
     name?: string | null;
     note?: string | null;
 }
-export interface AdjustCustomerBalanceParams {
-    amount: number;
-    reason?: string;
-}
 export interface FeedbackReply {
     id: string;
     content: string;
@@ -869,19 +865,20 @@ export interface WebhookTestData {
     webhookId: string;
     sample: Partial<OrderPaidData>;
 }
-export type OrderEventData = Omit<Order, 'serialsCount' | 'serialsReplaced' | 'replacements'> & {
+export type OrderEventData = Omit<Order, 'serialsCount' | 'serialsReplaced' | 'serials' | 'replacements'> & {
     previousStatus: OrderStatus | null;
+    /** Dedupe key: `order.created:<orderId>`, `order.updated:<orderId>:<transition>` or `order.canceled:<orderId>`. */
+    idempotencyKey: string;
 };
-export interface OrderReplacedData extends Omit<Order, 'serialsCount' | 'serialsReplaced' | 'replacements'> {
+export interface OrderReplacedData extends Omit<Order, 'serialsCount' | 'serialsReplaced' | 'serials' | 'replacements'> {
+    /** Dedupe key: `order.replaced:<orderId>:<first new serial id>`. */
+    idempotencyKey: string;
     reason: string | null;
-    replacements: Array<{
-        productId: string;
-        oldSerialId: string;
-        newSerialId: string;
-        key: string;
-    }>;
+    replacements: Array<OrderKeyReplacement>;
 }
 export interface QueryEventData {
+    /** Dedupe key: `query.created:<queryId>` or `query.replied:<messageId>`. */
+    idempotencyKey: string;
     queryId: string;
     title: string;
     status: QueryStatus;
@@ -895,6 +892,8 @@ export interface QueryEventData {
     };
 }
 export interface FeedbackReceivedData {
+    /** Dedupe key: `feedback.received:<feedbackId>`. */
+    idempotencyKey: string;
     feedbackId: string;
     productId: string;
     productName: string;

package/dist/esm/index.d.ts

@@ -1,6 +1,6 @@
-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';
+import type { AccessRule, AddAccessRuleParams, AddSerialsParams, AddSerialsResult, 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 declare const VERSION = "1.4.0";
 export interface SkalpOptions {
     apiKey?: string;
     webhookSecret?: string;
@@ -79,7 +79,6 @@ export declare class Skalp {
         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>;

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '1.3.0';
+export const VERSION = '1.4.0';
 const SIGNATURE_HEADER = 'skalp-signature';
 const SIGNATURE_TOLERANCE_SECONDS = 300;
 const USER_AGENT = `skalp-node/${VERSION}`;
@@ -179,7 +179,6 @@ export class Skalp {
         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 } }),

package/dist/esm/types.d.ts

@@ -60,6 +60,8 @@ export interface Order {
     deliveryStatus: DeliveryStatus | null;
     serialsCount?: number;
     serialsReplaced?: number;
+    /** Delivered and replaced keys by id, never their values. Only orders.get and orders.cancel fill it in. */
+    serials?: Array<OrderSerial>;
     createdAt: string;
     updatedAt: string;
     completedAt: string | null;
@@ -68,6 +70,14 @@ export interface Order {
     items?: Array<OrderItem>;
     replacements?: Array<OrderReplacement>;
 }
+export interface OrderSerial {
+    id: string;
+    productId: string;
+    status: 'DELIVERED' | 'REPLACED';
+    deliveredAt: string | null;
+    /** The serial that took this one's place, once replaced. */
+    replacedById: string | null;
+}
 export interface OrderReplacement {
     id: string;
     productId: string;
@@ -427,7 +437,6 @@ export interface Customer {
     name: string | null;
     note: string | null;
     country: string | null;
-    balance: number;
     ordersCount: number;
     totalSpent: number;
     currency: Currency;
@@ -436,17 +445,8 @@ export interface Customer {
     createdAt: string;
     updatedAt: string;
 }
-export interface CustomerBalanceEntry {
-    id: string;
-    amount: number;
-    balanceAfter: number;
-    reason: string | null;
-    orderId: string | null;
-    createdAt: string;
-}
 export interface CustomerDetails extends Customer {
     recentOrders: Array<Order>;
-    balanceHistory: Array<CustomerBalanceEntry>;
 }
 export interface ListCustomersParams {
     search?: string;
@@ -468,10 +468,6 @@ export interface UpdateCustomerParams {
     name?: string | null;
     note?: string | null;
 }
-export interface AdjustCustomerBalanceParams {
-    amount: number;
-    reason?: string;
-}
 export interface FeedbackReply {
     id: string;
     content: string;
@@ -869,19 +865,20 @@ export interface WebhookTestData {
     webhookId: string;
     sample: Partial<OrderPaidData>;
 }
-export type OrderEventData = Omit<Order, 'serialsCount' | 'serialsReplaced' | 'replacements'> & {
+export type OrderEventData = Omit<Order, 'serialsCount' | 'serialsReplaced' | 'serials' | 'replacements'> & {
     previousStatus: OrderStatus | null;
+    /** Dedupe key: `order.created:<orderId>`, `order.updated:<orderId>:<transition>` or `order.canceled:<orderId>`. */
+    idempotencyKey: string;
 };
-export interface OrderReplacedData extends Omit<Order, 'serialsCount' | 'serialsReplaced' | 'replacements'> {
+export interface OrderReplacedData extends Omit<Order, 'serialsCount' | 'serialsReplaced' | 'serials' | 'replacements'> {
+    /** Dedupe key: `order.replaced:<orderId>:<first new serial id>`. */
+    idempotencyKey: string;
     reason: string | null;
-    replacements: Array<{
-        productId: string;
-        oldSerialId: string;
-        newSerialId: string;
-        key: string;
-    }>;
+    replacements: Array<OrderKeyReplacement>;
 }
 export interface QueryEventData {
+    /** Dedupe key: `query.created:<queryId>` or `query.replied:<messageId>`. */
+    idempotencyKey: string;
     queryId: string;
     title: string;
     status: QueryStatus;
@@ -895,6 +892,8 @@ export interface QueryEventData {
     };
 }
 export interface FeedbackReceivedData {
+    /** Dedupe key: `feedback.received:<feedbackId>`. */
+    idempotencyKey: string;
     feedbackId: string;
     productId: string;
     productName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skalpgg/sdk",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Official Skalp SDK for Node.js and edge runtimes: checkout, subscriptions, catalog and key stock, webhooks and license verification.",
   "license": "MIT",
   "homepage": "https://skalp.gg/docs/sdk",