@spindlecommerce/plugin-sdk 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The SpindleCommerce authors
+
+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

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @spindlecommerce/plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The plugin API for [SpindleCommerce](https://spindlecommerce.com). A plugin adds to the platform
+without changing its code: a payment or shipping provider, an email or ERP integration, a fraud
+check, GraphQL fields, HTTP routes or scheduled tasks. Staff switch plugins on and fill in their
+settings in the admin, under **Settings › Plugins**.
+
+## Writing a plugin
+
+The quickest start is the template,
+[spindlecommerce/plugin-hello-world](https://github.com/spindlecommerce/plugin-hello-world). By hand:
+
+```bash
+pnpm add -D @spindlecommerce/plugin-sdk
+```
+
+```jsonc
+// package.json
+"peerDependencies": { "@spindlecommerce/plugin-sdk": "^1.0.0" }
+```
+
+```ts
+import { definePlugin, setting } from "@spindlecommerce/plugin-sdk";
+
+export const hello = () =>
+  definePlugin({
+    name: "hello",
+    version: "1.0.0",
+    apiVersion: 1,
+    title: "Hello",
+    settings: { greeting: setting.string({ label: "Greeting", default: "Hello" }) },
+    events: {
+      "order.placed": async (event, ctx) => ctx.logger.info({ orderId: event.aggregateId }, ctx.settings.greeting),
+    },
+  });
+```
+
+- **The peer dependency matters.** In an installation, `@spindlecommerce/plugin-sdk` is the
+  platform's own SDK, and the peer dependency makes your plugin use it. Then errors such as
+  `PaymentDeclinedError` are the ones the platform checks for.
+- **Write `apiVersion` as a number.** Inside an installation `PLUGIN_API_VERSION` is the platform's
+  own, so a plugin that used it would always claim to match.
+- **Publish JavaScript.** Build with `tsc` to `dist/`. Installations load plugins from
+  `node_modules`, where Node does not strip TypeScript types.
+- **Handlers run at least once.** An event can be delivered again after a timeout. Use `ctx.once`
+  for anything that must happen once, such as sending an email.
+
+## Installing a plugin
+
+In an installation:
+
+```bash
+pnpm add @spindlecommerce/plugin-hello-world
+```
+
+```ts
+// ecom.config.ts
+import { helloWorld } from "@spindlecommerce/plugin-hello-world";
+
+export default defineConfig({ plugins: [stripe(), email(), helloWorld()] });
+```
+
+Deploy, then open **Settings › Plugins**. A plugin starts working once every required setting has a
+value.
+
+## What's in it
+
+- `definePlugin`, `defineConfig`, `setting` and `PLUGIN_API_VERSION`.
+- The errors plugins throw: `ValidationError`, `NotFoundError`, `InvalidStateError` and
+  `PaymentDeclinedError`.
+- Types for every extension point: events, the checkout hook, payment and shipping providers, HTTP
+  routes, scheduled tasks, migrations and GraphQL.
+- The handler context, `PluginContext`: settings, logger, key-value storage, `once`, `emit`, `fetch`
+  and the platform's services.
+
+`ctx.db` is the platform's PostgreSQL database (Drizzle), for your plugin's own tables. In this
+package, `ctx.platform` and the GraphQL builder, refs and context have loose types. They are internal
+to the platform, and in an installation they have its precise types.
+
+## Versions
+
+The major version is the plugin API version: 1.x is `apiVersion: 1`. A platform refuses, at startup,
+a plugin written for another API version. Minor versions add to the API without breaking plugins.
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Expected failures. Services throw these; the GraphQL layer turns each class into a typed
+ * error object in the mutation's result union instead of an untyped top-level error.
+ */
+export declare class DomainError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type FieldError = {
+    path: string[];
+    message: string;
+};
+export declare class ValidationError extends DomainError {
+    readonly fieldErrors: FieldError[];
+    constructor(message: string, fieldErrors?: FieldError[]);
+}
+export declare class NotFoundError extends DomainError {
+    readonly resource: string;
+    readonly lookup: string;
+    constructor(resource: string, lookup: string);
+}
+export declare class ConflictError extends DomainError {
+    constructor(message: string);
+}
+export declare class AuthenticationError extends DomainError {
+    constructor(message?: string);
+}
+export declare class PermissionDeniedError extends DomainError {
+    readonly permission: string;
+    constructor(permission: string);
+}
+export declare class InsufficientStockError extends DomainError {
+    readonly variantId: string;
+    readonly sku: string;
+    readonly requested: number;
+    readonly available: number;
+    constructor(input: {
+        variantId: string;
+        sku: string;
+        requested: number;
+        available: number;
+    });
+}
+export declare class CouponNotApplicableError extends DomainError {
+    readonly couponCode: string;
+    readonly reason: string;
+    constructor(couponCode: string, reason: string);
+}
+export declare class CartNotReadyError extends DomainError {
+    readonly missing: string[];
+    /** The same, field by field. */
+    readonly fieldErrors: FieldError[];
+    constructor(missing: string[], fieldErrors?: FieldError[]);
+}
+export declare class PaymentDeclinedError extends DomainError {
+    readonly declineCode: string;
+    constructor(declineCode: string, message: string);
+}
+/** The entity exists but is in a state that does not allow the operation (e.g. refunding more than captured). */
+export declare class InvalidStateError extends DomainError {
+    constructor(message: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,623 @@
+/**
+ * The plugin API. A plugin is a value made with `definePlugin`, listed in ecom.config.ts and bundled
+ * with the app, so it runs wherever the platform does, serverless hosts included. Staff enable it
+ * and fill in its settings in the admin (Settings › Plugins).
+ *
+ * Plugins import this module, as @spindlecommerce/plugin-sdk, and nothing else of the platform: it
+ * is the surface kept stable across releases (`apiVersion`). The rest of the code base is internal;
+ * `ctx.platform` reaches it when a plugin must, at the cost of that promise.
+ *
+ * Extension points are typed and explicit (no patching of core code, so two plugins cannot fight
+ * over a method):
+ * - events: domain events after they commit, delivered at least once with retries;
+ * - hooks: a few synchronous checks on hot paths (checkout), each time-limited;
+ * - payments and shipping: providers that payment and shipping methods use;
+ * - graphql: types and fields on the admin or storefront API;
+ * - routes: HTTP endpoints under /plugins/<name>/, e.g. for webhooks from other services;
+ * - tasks: periodic jobs run by the worker;
+ * - migrations: SQL for the plugin's own tables;
+ * - admin: pages, navigation entries and widgets bundled into the admin app.
+ */
+import type { Context as HonoContext, Hono } from "hono";
+import type { Logger } from "pino";
+import type { Database } from "./internal.js";
+import type { builder as Builder, SubGraph } from "./internal.js";
+import type { GraphQLContext } from "./internal.js";
+import type * as Refs from "./refs.js";
+import type { Address } from "./internal.js";
+import type { Platform } from "./internal.js";
+export { InvalidStateError, NotFoundError, PaymentDeclinedError, ValidationError } from "./errors.js";
+export type { Address };
+/** The plugin API this platform implements. A plugin built for another version is refused at startup. */
+export declare const PLUGIN_API_VERSION = 1;
+type FieldBase = {
+    label: string;
+    description?: string;
+    /**
+     * An environment variable that supplies the value instead (e.g. STRIPE_SECRET_KEY). When it is
+     * set, the admin shows the field as set by the environment and read-only.
+     */
+    env?: string;
+};
+export type StringField = FieldBase & {
+    type: "string";
+    required?: boolean;
+    default?: string;
+    placeholder?: string;
+    multiline?: boolean;
+};
+/** Encrypted at rest and write-only: the admin API reports whether it is set, never the value. */
+export type SecretField = FieldBase & {
+    type: "secret";
+    required?: boolean;
+};
+export type BooleanField = FieldBase & {
+    type: "boolean";
+    default?: boolean;
+};
+export type NumberField = FieldBase & {
+    type: "number";
+    required?: boolean;
+    default?: number;
+    min?: number;
+    max?: number;
+    integer?: boolean;
+};
+export type SelectField<V extends string = string> = FieldBase & {
+    type: "select";
+    options: readonly {
+        value: V;
+        label: string;
+    }[];
+    required?: boolean;
+    default?: V;
+};
+export type SettingField = StringField | SecretField | BooleanField | NumberField | SelectField;
+export type SettingsShape = Record<string, SettingField>;
+type Present<F> = F extends {
+    required: true;
+} ? true : F extends {
+    default: unknown;
+} ? true : false;
+type FieldValue<F> = F extends {
+    type: "boolean";
+} ? boolean : F extends {
+    type: "number";
+} ? Present<F> extends true ? number : number | undefined : F extends SelectField<infer V> ? Present<F> extends true ? V : V | undefined : Present<F> extends true ? string : string | undefined;
+/**
+ * Settings as plugin code sees them. Required fields are always present: the platform runs a
+ * plugin's handlers and providers only once every required setting has a value ("configured").
+ */
+export type SettingsValues<S extends SettingsShape> = {
+    readonly [K in keyof S]: FieldValue<S[K]>;
+};
+/** Field builders: `settings: { apiKey: setting.secret({ label: "API key", required: true, env: "ACME_API_KEY" }) }`. */
+export declare const setting: {
+    string: <const F extends Omit<StringField, "type">>(field: F) => F & {
+        type: "string";
+    };
+    secret: <const F extends Omit<SecretField, "type">>(field: F) => F & {
+        type: "secret";
+    };
+    boolean: <const F extends Omit<BooleanField, "type">>(field: F) => F & {
+        type: "boolean";
+    };
+    number: <const F extends Omit<NumberField, "type">>(field: F) => F & {
+        type: "number";
+    };
+    select: <const V extends string, const F extends Omit<SelectField<V>, "type">>(field: F & {
+        options: readonly {
+            value: V;
+            label: string;
+        }[];
+    }) => F & {
+        options: readonly {
+            value: V;
+            label: string;
+        }[];
+        type: "select";
+    };
+};
+/** Plugin-scoped storage (one namespace per plugin), for state that needs no table of its own. */
+export type PluginKeyValueStore = {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    /** Set only when absent; returns whether it was set. */
+    add(key: string, value: unknown, options?: {
+        ttlSeconds?: number;
+    }): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    /** Entries whose key starts with `prefix`, in key order. */
+    list<T = unknown>(prefix: string, options?: {
+        limit?: number;
+    }): Promise<{
+        key: string;
+        value: T;
+    }[]>;
+};
+export type TrackingNumber = {
+    carrier: string;
+    number: string;
+    url?: string | null;
+};
+/** An order as plugins see it. Amounts are integer minor units in the order's currency. */
+export type PluginOrder = {
+    id: string;
+    number: string;
+    channelId: string;
+    customerId: string | null;
+    email: string;
+    locale: string;
+    currency: string;
+    status: string;
+    paymentStatus: string;
+    fulfillmentStatus: string;
+    subtotal: number;
+    discountTotal: number;
+    shippingTotal: number;
+    taxTotal: number;
+    grandTotal: number;
+    pricesIncludeTax: boolean;
+    shippingAddress: Address | null;
+    billingAddress: Address | null;
+    /** The shipping rate chosen at checkout; `details` comes from its provider (see RateQuote.data). */
+    shippingMethod: {
+        code: string;
+        name: string;
+        carrier: string;
+        amount: number;
+        details?: ShippingRateDetails | null;
+    } | null;
+    paymentMethodCode: string;
+    lines: {
+        id: string;
+        productId: string | null;
+        variantId: string | null;
+        sku: string;
+        name: string;
+        variantAttributes: Record<string, string>;
+        quantity: number;
+        quantityFulfilled: number;
+        unitPrice: number;
+        total: number;
+        weightGrams: number | null;
+        isShippable: boolean;
+    }[];
+    fulfillments: {
+        id: string;
+        number: string;
+        tracking: TrackingNumber[];
+        lines: {
+            orderLineId: string;
+            quantity: number;
+        }[];
+        createdAt: Date;
+    }[];
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+};
+export type PluginChannel = {
+    id: string;
+    code: string;
+    name: string;
+    defaultLocale: string;
+    storefrontUrl: string | null;
+};
+/** Read models and a few operations, stable across releases. */
+export type PluginServices = {
+    orders: {
+        get(id: string): Promise<PluginOrder | null>;
+        getByNumber(number: string): Promise<PluginOrder | null>;
+        /** A note in the order's history, attributed to the plugin. */
+        addNote(orderId: string, message: string): Promise<void>;
+    };
+    customers: {
+        /** `locale`: the one they last shopped in (their latest order's, else their latest cart's); null when they have neither. */
+        get(id: string): Promise<{
+            id: string;
+            email: string;
+            firstName: string | null;
+            lastName: string | null;
+            locale: string | null;
+        } | null>;
+    };
+    channels: {
+        /** `storefrontUrl`: the first storefront registered for the channel (Settings › Storefronts), if any. */
+        get(id: string): Promise<PluginChannel | null>;
+        /**
+         * The channel a request that names none uses (DEFAULT_CHANNEL, else the first active channel),
+         * e.g. for messages to customers and staff, who belong to no channel.
+         */
+        getDefault(): Promise<PluginChannel | null>;
+    };
+    locations: {
+        /** Where a channel's orders ship from: its first active stock location with an address. */
+        shipFrom(channelId: string): Promise<{
+            id: string;
+            name: string;
+            address: Partial<Address>;
+        } | null>;
+    };
+};
+export type PluginContext<S extends SettingsShape = SettingsShape> = {
+    plugin: {
+        name: string;
+        version: string;
+    };
+    settings: SettingsValues<S>;
+    db: Database;
+    /** A child logger tagged with the plugin's name. */
+    logger: Logger;
+    kv: PluginKeyValueStore;
+    /** The platform's fetch: use it rather than the global one, so tests can stand in for remote services. */
+    fetch: typeof fetch;
+    /**
+     * Run `fn` once per key across retries and instances (e.g. one confirmation email per order).
+     * Returns false when it had already run. A throwing `fn` does not count as run.
+     */
+    once(key: string, fn: () => Promise<void>): Promise<boolean>;
+    /**
+     * Emit one of the plugin's declared events (`emits`). Pass the transaction's `db` to commit it with
+     * other writes; webhooks and other plugins receive it like a platform event.
+     */
+    emit(event: {
+        type: string;
+        aggregateType: string;
+        aggregateId: string;
+        payload?: Record<string, unknown>;
+    }, db?: Database): Promise<void>;
+    services: PluginServices;
+    urls: {
+        /** The admin's public URL, e.g. https://shop-api.example.com/admin. */
+        admin: string;
+        /** This API's public base URL; the plugin's routes are at `${urls.api}/plugins/<name>/…`. */
+        api: string;
+    };
+    production: boolean;
+    /** Everything else, internal and not covered by `apiVersion`. */
+    platform: Platform;
+};
+/** A committed domain event: platform events (see EVENT_TYPES) and plugins' declared events. */
+export type PluginEvent = {
+    id: string;
+    type: string;
+    aggregateType: string;
+    aggregateId: string;
+    payload: Record<string, unknown>;
+    occurredAt: Date;
+};
+/**
+ * Runs after the event commits, outside any request, at least once: a handler that throws is
+ * retried with backoff, so make it idempotent (see `ctx.once`). Order across events is not guaranteed.
+ */
+export type EventHandler<S extends SettingsShape = SettingsShape> = (event: PluginEvent, ctx: PluginContext<S>) => Promise<void>;
+export type CheckoutValidateInput = {
+    cartId: string;
+    channelId: string;
+    customerId: string | null;
+    email: string | null;
+    currency: string;
+    grandTotal: number;
+    shippingAddress: Address | null;
+    billingAddress: Address | null;
+    shippingMethodCode: string | null;
+    paymentMethodCode: string | null;
+    lines: {
+        productId: string;
+        variantId: string;
+        sku: string;
+        quantity: number;
+        unitPrice: number;
+    }[];
+};
+export type CheckoutIssue = {
+    code: string;
+    message: string;
+    field?: string[];
+};
+export type PluginHooks<S extends SettingsShape> = {
+    /** Before an order is placed. Any issue refuses the order with a validation error. Limited to 5 seconds. */
+    checkoutValidate?: (input: CheckoutValidateInput, ctx: PluginContext<S>) => Promise<CheckoutIssue[]> | CheckoutIssue[];
+};
+export type PaymentSessionInput = {
+    cartId: string;
+    methodCode: string;
+    amount: number;
+    currency: string;
+    locale: string;
+    email: string | null;
+    customerId: string | null;
+    billingAddress: Address | null;
+    shippingAddress: Address | null;
+    lines: {
+        sku: string;
+        name: string;
+        quantity: number;
+        unitPrice: number;
+        total: number;
+    }[];
+    captureImmediately: boolean;
+    /** This cart's last session with the same provider: update it (e.g. a new amount) rather than start over. */
+    previous: Record<string, unknown> | null;
+};
+/** `data` stays on the server with the cart; `clientData` goes to the storefront (e.g. a client secret). */
+export type PaymentSession = {
+    data: Record<string, unknown>;
+    clientData: Record<string, unknown>;
+};
+export type AuthorizeInput = {
+    orderId: string;
+    orderNumber: string;
+    cartId: string | null;
+    amount: number;
+    currency: string;
+    /**
+     * What the storefront sent with the order (e.g. a test token). When the platform places the
+     * order itself from a webhook (a customer who paid but never came back to the storefront), it is
+     * `{ pspReference }`: the payment the PSP reported.
+     */
+    paymentData: Record<string, unknown>;
+    captureImmediately: boolean;
+    /** The cart's session `data`, when the provider created one. */
+    session: Record<string, unknown> | null;
+};
+/** Throw PaymentDeclinedError to decline: the order is canceled, its stock released and the cart reopened. */
+export type AuthorizeResult = {
+    status: "authorized" | "captured" | "pending";
+    pspReference: string | null;
+    raw?: Record<string, unknown>;
+};
+export type ProviderResult = {
+    pspReference: string | null;
+    raw?: Record<string, unknown>;
+};
+/** A payment event a provider reports from a webhook. The platform applies each once, by `id`. */
+export type PaymentWebhookEvent = {
+    /** The PSP's own event id, for idempotency. */
+    id: string;
+    type: "authorized" | "captured" | "failed" | "canceled" | "refunded" | "dispute_opened" | "dispute_closed";
+    /** The payment's reference (what authorize returned as pspReference). */
+    pspReference: string;
+    /** Required for `refunded`: the refund's own reference, so each refund is recorded once. */
+    refundReference?: string;
+    /** Minor units. For `captured`, the total captured so far (cumulative), not this capture alone. */
+    amount?: number;
+    currency?: string;
+    /** Where the PSP carries them (e.g. metadata): lets a payment completed without the storefront still become an order. */
+    orderId?: string;
+    cartId?: string;
+    reason?: string;
+    raw?: Record<string, unknown>;
+};
+/** `response` replaces the default 200 `{ "received": true }`. */
+export type PaymentWebhookResult = {
+    events: PaymentWebhookEvent[];
+    response?: Response;
+};
+/**
+ * A payment service provider (PSP). Payment methods (Settings › Payments) pick a provider; the
+ * platform owns orders, transactions and invoices, the provider talks to the PSP.
+ *
+ * Checkout: the storefront may ask for a session (createSession) to render the PSP's own payment
+ * UI, then places the order; authorize then confirms the payment, normally by checking with the
+ * PSP what happened in the browser. Webhooks (POST /payments/webhooks/<code>) report what happens
+ * later, and complete orders whose customer never came back from the PSP.
+ */
+export interface PaymentProviderDefinition<S extends SettingsShape = SettingsShape> {
+    /** Unique across plugins, e.g. "stripe". */
+    readonly code: string;
+    readonly title: string;
+    readonly description?: string;
+    /** Offered at checkout only when this returns true (defaults to true). */
+    isAvailable?(input: {
+        currency: string;
+        countryCode: string | null;
+        amount: number;
+    }, ctx: PluginContext<S>): boolean | Promise<boolean>;
+    createSession?(input: PaymentSessionInput, ctx: PluginContext<S>): Promise<PaymentSession>;
+    authorize(input: AuthorizeInput, ctx: PluginContext<S>): Promise<AuthorizeResult>;
+    capture(input: {
+        orderId: string;
+        amount: number;
+        currency: string;
+        pspReference: string | null;
+    }, ctx: PluginContext<S>): Promise<ProviderResult>;
+    refund(input: {
+        orderId: string;
+        amount: number;
+        currency: string;
+        pspReference: string | null;
+    }, ctx: PluginContext<S>): Promise<ProviderResult>;
+    /**
+     * Cancel an order's authorization. An empty `orderId` means: release a session's payment that no
+     * order came of (stock ran out after the customer confirmed, a check refused the order). Give back
+     * whatever it secured, found by `pspReference` or the cart's session `data` (`session`), and leave
+     * an unpaid one usable.
+     */
+    void(input: {
+        orderId: string;
+        pspReference: string | null;
+        session?: Record<string, unknown> | null;
+    }, ctx: PluginContext<S>): Promise<ProviderResult>;
+    /**
+     * Verify (signatures!) and translate a PSP webhook. Throw ValidationError when the request cannot
+     * be verified: the route answers 400 without details.
+     */
+    webhook?(request: Request, ctx: PluginContext<S>): Promise<PaymentWebhookResult>;
+}
+export type RateRequest = {
+    /** The shipping method being priced; `options` are its provider options (ShippingProviderDefinition.methodOptions). */
+    method: {
+        id: string;
+        code: string;
+        name: string;
+        options: Record<string, unknown>;
+    };
+    channelId: string;
+    locale: string;
+    currency: string;
+    /** After discounts, minor units. */
+    subtotal: number;
+    weightGrams: number;
+    quantity: number;
+    destination: Address;
+    origin: Partial<Address> | null;
+    /** `weightGrams` and `unitPrice` are per unit. */
+    lines: {
+        sku: string;
+        name: string;
+        quantity: number;
+        weightGrams: number;
+        unitPrice: number;
+    }[];
+};
+/** One rate. `code` is unique within the method (e.g. a service level); `data` is kept with the order (e.g. a carrier rate id). */
+export type RateQuote = {
+    code: string;
+    name: string;
+    amount: number;
+    carrier?: string | null;
+    minDeliveryDays?: number | null;
+    maxDeliveryDays?: number | null;
+    data?: Record<string, unknown>;
+};
+/** Stored with the order's shipping method, so fulfilment knows which provider, method and rate were chosen. */
+export type ShippingRateDetails = {
+    provider: string;
+    method: string;
+    rate: string;
+    data: Record<string, unknown>;
+};
+export type ShipmentRequest = {
+    order: PluginOrder;
+    /** The units being shipped. */
+    lines: {
+        orderLineId: string;
+        sku: string;
+        name: string;
+        quantity: number;
+        weightGrams: number | null;
+    }[];
+    origin: Partial<Address> | null;
+    /** The method's provider options and the rate chosen at checkout, when the order used this provider. */
+    method: {
+        code: string;
+        options: Record<string, unknown>;
+    } | null;
+    rate: ShippingRateDetails | null;
+};
+export type ShipmentResult = {
+    tracking: TrackingNumber[];
+    labelUrl?: string | null;
+    cost?: {
+        amount: number;
+        currency: string;
+    } | null;
+    data?: Record<string, unknown>;
+};
+/**
+ * A carrier or rate engine. Shipping methods (Settings › Shipping) pick a provider and set its
+ * options. Live rates are cached per request for `cacheSeconds` (default 600) and never fetched
+ * while an order is being written, so slow carriers cannot hold up checkout.
+ */
+export interface ShippingProviderDefinition<S extends SettingsShape = SettingsShape> {
+    /** Unique across plugins, e.g. "shippo". */
+    readonly code: string;
+    readonly title: string;
+    readonly description?: string;
+    /** Options per shipping method, e.g. carriers or a markup. Secrets belong in plugin settings, not here. */
+    readonly methodOptions?: SettingsShape;
+    readonly cacheSeconds?: number;
+    /** Rates for a cart; [] when none apply. Limited to 10 seconds. */
+    rates(input: RateRequest, ctx: PluginContext<S>): Promise<RateQuote[]>;
+    /** Buy a label or book the shipment when staff fulfil (on request). */
+    createShipment?(input: ShipmentRequest, ctx: PluginContext<S>): Promise<ShipmentResult>;
+    trackingUrl?(tracking: {
+        carrier: string;
+        number: string;
+    }): string | null;
+}
+/**
+ * Run by the worker at most once per interval, on one instance at a time. On serverless hosts the
+ * worker runs on each cron call and with traffic, so the interval is a minimum, not a schedule.
+ */
+export type ScheduledTask<S extends SettingsShape = SettingsShape> = {
+    name: string;
+    description?: string;
+    intervalMinutes: number;
+    run(ctx: PluginContext<S>): Promise<void>;
+};
+export type RouteApi<S extends SettingsShape> = {
+    /** The plugin's context for a request; answers 503 for the plugin while it is disabled or not configured. */
+    context(c: HonoContext): Promise<PluginContext<S>>;
+};
+export type GraphQLExtensionApi<S extends SettingsShape> = {
+    /** The platform's Pothos builder: add types with `builder.objectType`, fields with `builder.queryField`, … */
+    builder: typeof Builder;
+    /** Sub-graphs for `subGraphs`: the admin API, the storefront API or both. */
+    ADMIN: SubGraph[];
+    STOREFRONT: SubGraph[];
+    BOTH: SubGraph[];
+    /** Object refs of platform types (OrderRef, ProductRef, CustomerRef, …), to add fields to them. */
+    refs: typeof Refs;
+    /** The plugin's context inside a resolver; fails with InvalidStateError while it is disabled or not configured. */
+    context(ctx: GraphQLContext): Promise<PluginContext<S>>;
+    /** Global ids: `gid://ecom/<Type>/<uuid>`. */
+    toGlobalId(type: string, id: string): string;
+    rawId(id: {
+        id: string;
+    } | string): string;
+};
+export type PluginDefinition<S extends SettingsShape = SettingsShape> = {
+    /** Unique: lowercase letters, digits and dashes. It namespaces settings, storage, routes and events. */
+    name: string;
+    /** The plugin's own version, shown in the admin. */
+    version: string;
+    /** The plugin API it was written for: PLUGIN_API_VERSION. */
+    apiVersion: number;
+    title: string;
+    description?: string;
+    settings?: S;
+    /** Permissions it introduces, e.g. `reviews:moderate`, assignable to roles and usable in its pages and fields. */
+    permissions?: {
+        code: string;
+        description: string;
+    }[];
+    /** Event types it emits, each `<name>.<something>`, so webhooks and other plugins can subscribe. */
+    emits?: string[];
+    /** Keys: an event type, `prefix.*` or `*`. */
+    events?: Record<string, EventHandler<S>>;
+    hooks?: PluginHooks<S>;
+    payments?: PaymentProviderDefinition<S>[];
+    shipping?: ShippingProviderDefinition<S>[];
+    /** Registered once per process, before the schema is built. */
+    graphql?: (api: GraphQLExtensionApi<S>) => void;
+    /** Mounted at /plugins/<name>/. */
+    routes?: (router: Hono, api: RouteApi<S>) => void;
+    tasks?: ScheduledTask<S>[];
+    /** A directory of `.sql` files, applied once each in name order after the platform's migrations: `new URL("./migrations/", import.meta.url)`. */
+    migrations?: URL;
+    /** The admin module (default export from `defineAdminPlugin`), bundled into the admin at build time: `new URL("./admin.tsx", import.meta.url)`. */
+    admin?: URL;
+    /** Once per process, when the platform starts and the plugin is enabled and configured. */
+    onStart?: (ctx: PluginContext<S>) => Promise<void> | void;
+    /**
+     * "Test connection" in the admin: check the settings against the remote service (e.g. that an
+     * API key works) and say what was found. Limited to 15 seconds.
+     */
+    check?: (ctx: PluginContext<S>) => Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+};
+/** Settings types flow into every handler: `ctx.settings.apiKey` is a string when the field is required. */
+export declare const definePlugin: <const S extends SettingsShape = Record<never, SettingField>>(definition: PluginDefinition<S>) => PluginDefinition<S>;
+/** Any plugin, whatever its settings. */
+export type AnyPluginDefinition = PluginDefinition<any>;
+export type EcomConfig = {
+    plugins: AnyPluginDefinition[];
+};
+/** ecom.config.ts: `export default defineConfig({ plugins: [stripe(), email()] })`. */
+export declare const defineConfig: (config: EcomConfig) => EcomConfig;

package/dist/index.js

@@ -0,0 +1,59 @@
+// errors.ts
+var DomainError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+  }
+};
+var ValidationError = class extends DomainError {
+  fieldErrors;
+  constructor(message, fieldErrors = []) {
+    super("VALIDATION_FAILED", message);
+    this.fieldErrors = fieldErrors;
+  }
+};
+var NotFoundError = class extends DomainError {
+  resource;
+  lookup;
+  constructor(resource, lookup) {
+    super("NOT_FOUND", `${resource} ${lookup} was not found`);
+    this.resource = resource;
+    this.lookup = lookup;
+  }
+};
+var PaymentDeclinedError = class extends DomainError {
+  declineCode;
+  constructor(declineCode, message) {
+    super("PAYMENT_DECLINED", message);
+    this.declineCode = declineCode;
+  }
+};
+var InvalidStateError = class extends DomainError {
+  constructor(message) {
+    super("INVALID_STATE", message);
+  }
+};
+
+// index.ts
+var PLUGIN_API_VERSION = 1;
+var setting = {
+  string: (field) => ({ ...field, type: "string" }),
+  secret: (field) => ({ ...field, type: "secret" }),
+  boolean: (field) => ({ ...field, type: "boolean" }),
+  number: (field) => ({ ...field, type: "number" }),
+  select: (field) => ({ ...field, type: "select" })
+};
+var definePlugin = (definition) => definition;
+var defineConfig = (config) => config;
+export {
+  InvalidStateError,
+  NotFoundError,
+  PLUGIN_API_VERSION,
+  PaymentDeclinedError,
+  ValidationError,
+  defineConfig,
+  definePlugin,
+  setting
+};

package/dist/internal.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Public stand-ins for the platform types the plugin API mentions, used by the copy of
+ * @spindlecommerce/plugin-sdk published to npm (scripts/plugin-sdk-package.ts). In an installation the
+ * package is the platform's own SDK, typed with the real ones.
+ *
+ * Only `Database` and `Address` are covered by `apiVersion`; the rest is internal to the platform, so
+ * it is typed loosely here.
+ */
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+/** The platform's PostgreSQL database (Drizzle), for the plugin's own tables. */
+export type Database = PgDatabase<PgQueryResultHKT>;
+/** A postal address; `countryCode` is ISO 3166-1 alpha-2. The same as the platform's (checked by test/unit/plugin-sdk-package.test.ts). */
+export type Address = {
+    firstName: string;
+    lastName: string;
+    company?: string | null;
+    line1: string;
+    line2?: string | null;
+    city: string;
+    region?: string | null;
+    regionCode?: string | null;
+    postalCode: string;
+    countryCode: string;
+    phone?: string | null;
+};
+/** `ctx.platform`: the rest of the platform, outside the plugin API. */
+export type Platform = unknown;
+/** What a GraphQL resolver receives as its context. */
+export type GraphQLContext = unknown;
+export type SubGraph = "storefront" | "admin";
+/** The platform's Pothos schema builder. */
+export declare const builder: any;

package/dist/refs.d.ts

@@ -0,0 +1,45 @@
+/** Object refs of the platform's GraphQL types, to add fields to. Typed in an installation. */
+export declare const MoneyRef: any;
+export declare const AddressRef: any;
+export declare const SessionRef: any;
+export declare const ChannelRef: any;
+export declare const AttributeDefinitionRef: any;
+export declare const ProductTypeRef: any;
+export declare const ProductRef: any;
+export declare const ProductVariantRef: any;
+export declare const MediaRef: any;
+export declare const CategoryRef: any;
+export declare const MediaAssetRef: any;
+export declare const CartRef: any;
+export declare const CartLineRef: any;
+export declare const CustomerRef: any;
+export declare const CustomerAddressRef: any;
+export declare const CustomerGroupRef: any;
+export declare const OrderRef: any;
+export declare const OrderLineRef: any;
+export declare const InvoiceRef: any;
+export declare const FulfillmentRef: any;
+export declare const RefundRef: any;
+export declare const OrderEventRef: any;
+export declare const PaymentTransactionRef: any;
+export declare const PromotionRef: any;
+export declare const CouponRef: any;
+export declare const StockLocationRef: any;
+export declare const StockRef: any;
+export declare const StockLevelRef: any;
+export declare const TaxClassRef: any;
+export declare const TaxRateRef: any;
+export declare const TaxRuleRef: any;
+export declare const ShippingZoneRef: any;
+export declare const ShippingMethodRef: any;
+export declare const PaymentMethodRef: any;
+export declare const PageRef: any;
+export declare const PageVersionRef: any;
+export declare const ComponentRef: any;
+export declare const ReleaseRef: any;
+export declare const FrontendRef: any;
+export declare const StaffUserRef: any;
+export declare const RoleRef: any;
+export declare const ApiKeyRef: any;
+export declare const WebhookSubscriptionRef: any;
+export declare const WebhookDeliveryRef: any;

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@spindlecommerce/plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "The plugin API for SpindleCommerce: payment and shipping providers, integrations, GraphQL fields, routes and scheduled tasks as plugins.",
+  "keywords": [
+    "spindlecommerce",
+    "ecommerce",
+    "plugin",
+    "sdk"
+  ],
+  "homepage": "https://spindlecommerce.com",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24.12"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.4",
+    "hono": "^4.13.13",
+    "pino": "^10.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}