@stable_sea/sdk 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# Stable Sea API SDK
+
+Typed Node.js client for the Stable Sea API.
+
+## Install
+
+```sh
+npm install @stable_sea/sdk@0.1
+```
+
+The package follows semantic versioning. Pin a minor version for pre-1.0 releases;
+minor releases may contain breaking SDK API changes. The dated API contract is
+independent of the npm package version and must be selected explicitly when you
+create a client:
+
+```ts
+import { createStableSeaClient } from "@stable_sea/sdk";
+
+const client = createStableSeaClient({
+  apiKey: process.env.STABLE_SEA_API_KEY!,
+  baseUrl: process.env.STABLE_SEA_BASE_URL!,
+  version: "2026-07-23",
+});
+```
+
+Node.js 20 or later is supported. Obtain the base URL and a credential from your
+Stable Sea contact; the public API is not deployed and credentials are not
+self-service. Use `sk_test_…` only with the development host and `sk_live_…` only
+with the production host. The credential identifies one business and carries
+fixed scopes, so do not send a `Stable-Sea-Account` header.
+
+| SDK | API contract | Credentials |
+|---|---|---|
+| `0.1.x` | `2026-07-23` | `sk_test_…` on development; `sk_live_…` on production |
+
+## Idempotent writes
+
+Create one mutation handle for one logical write. Its `POST` method always sends
+an `Idempotency-Key`; retry the same handle if the response is lost. Supply a
+key when the retry may continue in another process, and reuse that exact key for
+the same logical operation.
+
+```ts
+const placeOrder = client.mutation();
+const response = await placeOrder.POST("/v1/orders", { body: order });
+// Retry after a transport failure with the same handle (and therefore same key).
+const retry = await placeOrder.POST("/v1/orders", { body: order });
+```
+
+## Webhooks
+
+Pass the exact raw request bytes to `verifyWebhookSignature` before parsing the
+body. It verifies HMAC-SHA256 in constant time and rejects signatures outside a
+five-minute window by default. Set `toleranceSeconds` only when your replay policy
+requires a different window.
+
+```ts
+import { verifyWebhookSignature } from "@stable_sea/sdk";
+
+const valid = await verifyWebhookSignature(
+  rawBody,
+  request.headers.get("Stable-Sea-Signature") ?? "",
+  process.env.STABLE_SEA_WEBHOOK_SECRET!,
+);
+```
+
+API request, response, pagination, and error types are generated from
+`services/backend/api/openapi.public.json` and exported as `paths`, `operations`,
+and `components`.

package/dist/client.d.ts

@@ -0,0 +1,47 @@
+import createClient from "openapi-fetch";
+import type { FetchResponse } from "openapi-fetch";
+import type { paths } from "./gen/schema.js";
+export interface StableSeaClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    version?: "2026-07-23";
+}
+type GeneratedClient = ReturnType<typeof createClient<paths>>;
+type MutationPath = {
+    [Path in keyof paths]: paths[Path] extends {
+        post: unknown;
+    } ? Path : never;
+}[keyof paths];
+type MutationOperation<Path extends MutationPath> = paths[Path] extends {
+    post: infer Operation;
+} ? Operation : never;
+type MutationParameters<Path extends MutationPath> = MutationOperation<Path> extends {
+    parameters: infer Parameters;
+} ? Omit<Parameters, "header"> : never;
+type MutationBody<Path extends MutationPath> = MutationOperation<Path> extends {
+    requestBody?: {
+        content: {
+            "application/json": infer Body;
+        };
+    };
+} ? Body : never;
+type MutationInit<Path extends MutationPath> = {
+    body?: MutationBody<Path>;
+} & ({} extends MutationParameters<Path> ? {
+    params?: MutationParameters<Path>;
+} : {
+    params: MutationParameters<Path>;
+});
+type MutationResponse<Path extends MutationPath> = Promise<FetchResponse<MutationOperation<Path> & Record<string, unknown>, MutationInit<Path>, "application/json">>;
+export interface StableSeaMutation {
+    idempotencyKey: string;
+    POST<Path extends MutationPath>(path: Path, init: MutationInit<Path>): MutationResponse<Path>;
+}
+export interface StableSeaMutationOptions {
+    idempotencyKey?: string;
+}
+export type StableSeaClient = Omit<GeneratedClient, "POST"> & {
+    mutation(options?: StableSeaMutationOptions): StableSeaMutation;
+};
+export declare function createStableSeaClient(options: StableSeaClientOptions): StableSeaClient;
+export {};

package/dist/client.js

@@ -0,0 +1,42 @@
+import createClient from "openapi-fetch";
+function mutationKey(options) {
+    if (options.idempotencyKey === "")
+        throw new Error("idempotencyKey is required");
+    return options.idempotencyKey ?? crypto.randomUUID();
+}
+export function createStableSeaClient(options) {
+    if (!options.apiKey)
+        throw new Error("apiKey is required");
+    if (!options.baseUrl)
+        throw new Error("baseUrl is required");
+    const rawClient = createClient({ baseUrl: options.baseUrl });
+    rawClient.use({
+        onRequest({ request }) {
+            request.headers.set("Authorization", `Bearer ${options.apiKey}`);
+            // No Stable-Sea-Account. The API is single-tenant: the credential names
+            // the business, and every operation refuses that header with a coded 400.
+            // Sending it would brick every call the client makes.
+            if (options.version)
+                request.headers.set("Stable-Sea-Version", options.version);
+            return request;
+        },
+    });
+    const { POST, ...client } = rawClient;
+    const post = POST;
+    return Object.assign(client, {
+        mutation(mutationOptions = {}) {
+            const idempotencyKey = mutationKey(mutationOptions);
+            const idempotentPost = (path, init) => post(path, {
+                ...init,
+                params: {
+                    ...(init.params ?? {}),
+                    header: { "Idempotency-Key": idempotencyKey },
+                },
+            });
+            return {
+                idempotencyKey,
+                POST: idempotentPost,
+            };
+        },
+    });
+}