@kaching.sh/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kaching
+
+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,20 @@
+# @kaching.sh/sdk
+
+Typed client for the [kaching](https://kaching.sh) commerce API — products, carts, Stripe checkout,
+orders and digital downloads.
+
+```ts
+import { createKaching, formatMoney } from "@kaching.sh/sdk";
+
+const kaching = createKaching({ apiKey: process.env.KACHING_SECRET_KEY });
+const { data: products } = await kaching.products.list();
+const cart = await kaching.carts.create({ items: [{ variant_id: products[0].variants[0].id }] });
+const { url } = await kaching.carts.checkout(cart.id, {
+  success_url: "https://shop.example/checkout/success",
+  cancel_url: "https://shop.example/cart",
+});
+```
+
+Use a **publishable key** (`kc_pk_…`) in browsers — it can read the catalog and create carts and
+checkouts. Use a **secret key** (`kc_sk_…`) only on servers. Money is always an integer in minor
+units; format it with `formatMoney(amount, currency)`.

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+type ProductType = "physical" | "digital";
+type ProductStatus = "draft" | "active" | "archived";
+interface List<T> {
+    object: "list";
+    data: T[];
+    total?: number;
+    has_more?: boolean;
+}
+interface Store {
+    id: string;
+    object: "store";
+    name: string;
+    slug: string;
+    currency: string;
+    support_email: string | null;
+    storefront_url: string | null;
+    livemode: boolean;
+    payments: PaymentsStatus;
+    tax_enabled: boolean;
+    created_at: string;
+}
+interface PaymentsStatus {
+    connected: boolean;
+    card_payments_status: "active" | "pending" | "restricted" | "unsupported" | null;
+    ready: boolean;
+    checked_at: string | null;
+}
+interface CreatedStore extends Store {
+    /** Returned once at creation. Store them — they can't be retrieved again. */
+    keys: {
+        publishable: string;
+        secret: string;
+    };
+}
+interface Variant {
+    id: string;
+    object: "variant";
+    product_id: string;
+    title: string;
+    sku: string | null;
+    price: number;
+    compare_at_price: number | null;
+    options: Record<string, string>;
+    available: boolean;
+    position: number;
+    /** Secret key only */
+    track_inventory?: boolean;
+    /** Secret key only */
+    inventory_quantity?: number;
+    /** Secret key only */
+    weight_grams?: number | null;
+    /** Secret key only */
+    files?: DigitalFile[];
+}
+interface Product {
+    id: string;
+    object: "product";
+    title: string;
+    slug: string;
+    description: string | null;
+    type: ProductType;
+    status: ProductStatus;
+    images: string[];
+    metadata: Record<string, unknown>;
+    price_range: {
+        min: number;
+        max: number;
+    } | null;
+    variants: Variant[];
+    created_at: string;
+    updated_at: string;
+}
+interface DigitalFile {
+    id: string;
+    filename: string;
+    content_type: string | null;
+    size_bytes: number | null;
+}
+interface ShippingRate {
+    id: string;
+    object: "shipping_rate";
+    name: string;
+    amount: number;
+    countries: string[];
+    min_delivery_days: number | null;
+    max_delivery_days: number | null;
+    active: boolean;
+    created_at: string;
+}
+interface CartItem {
+    id: string;
+    variant_id: string;
+    product_id: string;
+    product_slug: string;
+    title: string;
+    variant_title: string | null;
+    options: Record<string, string>;
+    type: ProductType;
+    image: string | null;
+    unit_price: number;
+    quantity: number;
+    line_total: number;
+    available: boolean;
+}
+interface Cart {
+    id: string;
+    object: "cart";
+    status: "open" | "checking_out" | "completed" | "abandoned";
+    currency: string;
+    email: string | null;
+    items: CartItem[];
+    item_count: number;
+    subtotal: number;
+    requires_shipping: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface Checkout {
+    object: "checkout";
+    cart_id: string;
+    session_id: string;
+    /** Stripe Checkout URL — redirect the shopper here. */
+    url: string;
+    expires_at: number;
+}
+interface OrderItem {
+    id: string;
+    variant_id: string | null;
+    title: string;
+    variant_title: string | null;
+    sku: string | null;
+    type: ProductType;
+    unit_price: number;
+    quantity: number;
+    line_total: number;
+    downloads: {
+        filename: string;
+        url: string;
+        downloads_remaining: number;
+        expires_at: string;
+    }[];
+}
+interface Order {
+    id: string;
+    object: "order";
+    number: number;
+    status: "paid" | "fulfilled" | "refunded" | "canceled";
+    fulfillment_status: "unfulfilled" | "fulfilled" | "not_required";
+    email: string | null;
+    customer_name: string | null;
+    shipping_address: Record<string, string | null> | null;
+    shipping_rate_name: string | null;
+    currency: string;
+    subtotal: number;
+    shipping_total: number;
+    tax_total: number;
+    total: number;
+    items: OrderItem[];
+    created_at: string;
+    /** Secret key only */
+    application_fee?: number;
+}
+interface OnboardingLink {
+    object: "onboarding_link";
+    /** Stripe's single-use link; expires within minutes. */
+    url: string;
+    expires_at: string;
+    /** Durable (7 days) kaching link that opens a fresh Stripe onboarding page. Give this to humans. */
+    start_url: string;
+}
+interface VariantInput {
+    title?: string;
+    sku?: string | null;
+    price: number;
+    compare_at_price?: number | null;
+    options?: Record<string, string>;
+    track_inventory?: boolean;
+    inventory_quantity?: number;
+    weight_grams?: number | null;
+    position?: number;
+}
+interface ProductInput {
+    title: string;
+    slug?: string;
+    description?: string | null;
+    type?: ProductType;
+    status?: ProductStatus;
+    images?: string[];
+    metadata?: Record<string, unknown>;
+    /** Shortcut for single-variant products */
+    price?: number;
+    variants?: VariantInput[];
+}
+interface ShippingRateInput {
+    name: string;
+    amount: number;
+    /** ISO-3166 alpha-2 codes. Omit or empty for worldwide. */
+    countries?: string[];
+    min_delivery_days?: number | null;
+    max_delivery_days?: number | null;
+    active?: boolean;
+}
+interface CartItemInput {
+    variant_id: string;
+    quantity?: number;
+}
+interface CheckoutInput {
+    success_url: string;
+    cancel_url: string;
+    email?: string;
+}
+
+declare const DEFAULT_BASE_URL = "https://kaching.sh/api/v1";
+declare class KachingError extends Error {
+    status: number;
+    code: string;
+    details?: unknown | undefined;
+    constructor(status: number, code: string, message: string, details?: unknown | undefined);
+}
+interface KachingOptions {
+    /** kc_pk_... (browser-safe: catalog, carts, checkout) or kc_sk_... (server/agent: everything). */
+    apiKey?: string;
+    /** Clerk session token — only for account-level calls like `stores.create`. */
+    sessionToken?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+declare function createKaching(options?: KachingOptions): {
+    stores: {
+        /** Requires a Clerk session token. */
+        list: () => Promise<List<Store>>;
+        /** Requires a Clerk session token. Returns API keys once. */
+        create: (input: {
+            name: string;
+            slug?: string;
+            currency?: string;
+            support_email?: string;
+            storefront_url?: string;
+        }) => Promise<CreatedStore>;
+    };
+    store: {
+        get: () => Promise<Store>;
+        update: (input: Partial<Pick<Store, "name" | "currency" | "support_email" | "storefront_url" | "tax_enabled">>) => Promise<Store>;
+    };
+    payments: {
+        status: () => Promise<PaymentsStatus>;
+        /** Creates the Stripe account if needed and returns onboarding links. */
+        onboard: (input?: {
+            email?: string;
+            country?: string;
+        }) => Promise<OnboardingLink>;
+    };
+    products: {
+        list: (query?: {
+            status?: string;
+            type?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<List<Product>>;
+        /** By id or slug. */
+        get: (idOrSlug: string) => Promise<Product>;
+        create: (input: ProductInput) => Promise<Product>;
+        update: (idOrSlug: string, input: Partial<Omit<ProductInput, "price" | "variants">>) => Promise<Product>;
+        delete: (idOrSlug: string) => Promise<{
+            id: string;
+            deleted: true;
+        }>;
+        addVariant: (idOrSlug: string, input: VariantInput) => Promise<Product>;
+        /** Uploads an image (≤4 MB) and appends it to the product. */
+        uploadImage: (idOrSlug: string, file: Blob, filename?: string) => Promise<Product>;
+    };
+    variants: {
+        update: (id: string, input: Partial<VariantInput>) => Promise<Product>;
+        delete: (id: string) => Promise<{
+            id: string;
+            deleted: true;
+        }>;
+        files: {
+            list: (variantId: string) => Promise<List<DigitalFile>>;
+            /** Registers a file and uploads its bytes via the signed URL. */
+            upload: (variantId: string, file: Blob, filename: string) => Promise<DigitalFile>;
+        };
+    };
+    shippingRates: {
+        list: () => Promise<List<ShippingRate>>;
+        create: (input: ShippingRateInput) => Promise<ShippingRate>;
+        update: (id: string, input: Partial<ShippingRateInput>) => Promise<ShippingRate>;
+        delete: (id: string) => Promise<{
+            id: string;
+            deleted: true;
+        }>;
+    };
+    carts: {
+        create: (input?: {
+            items?: CartItemInput[];
+            email?: string;
+        }) => Promise<Cart>;
+        get: (id: string) => Promise<Cart>;
+        /** Adds to the existing quantity. */
+        addItem: (id: string, item: CartItemInput) => Promise<Cart>;
+        /** Sets the quantity; 0 removes the line. */
+        updateItem: (id: string, variantId: string, quantity: number) => Promise<Cart>;
+        removeItem: (id: string, variantId: string) => Promise<Cart>;
+        checkout: (id: string, input: CheckoutInput) => Promise<Checkout>;
+    };
+    checkout: {
+        /** "Buy now": creates a cart and a checkout in one call. */
+        create: (input: CheckoutInput & {
+            items: CartItemInput[];
+        }) => Promise<Checkout>;
+        /** The order for a completed Checkout Session. 404 until the payment webhook lands — poll briefly. */
+        getOrder: (sessionId: string) => Promise<Order>;
+    };
+    orders: {
+        list: (query?: {
+            fulfillment_status?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<List<Order>>;
+        get: (id: string) => Promise<Order>;
+        fulfill: (id: string) => Promise<Order>;
+    };
+};
+type Kaching = ReturnType<typeof createKaching>;
+/** Formats minor units: formatMoney(24900, "nok") → "NOK 249.00" (locale-aware). */
+declare function formatMoney(amount: number, currency: string, locale?: string): string;
+
+export { type Cart, type CartItem, type CartItemInput, type Checkout, type CheckoutInput, type CreatedStore, DEFAULT_BASE_URL, type DigitalFile, type Kaching, KachingError, type KachingOptions, type List, type OnboardingLink, type Order, type OrderItem, type PaymentsStatus, type Product, type ProductInput, type ProductStatus, type ProductType, type ShippingRate, type ShippingRateInput, type Store, type Variant, type VariantInput, createKaching, formatMoney };

package/dist/index.js

@@ -0,0 +1,137 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://kaching.sh/api/v1";
+var KachingError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.name = "KachingError";
+  }
+  status;
+  code;
+  details;
+};
+function createKaching(options = {}) {
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const token = options.apiKey ?? options.sessionToken;
+  async function request(method, path, body, query) {
+    const url = new URL(baseUrl + path);
+    for (const [k, v] of Object.entries(query ?? {})) if (v !== void 0) url.searchParams.set(k, String(v));
+    const isForm = typeof FormData !== "undefined" && body instanceof FormData;
+    const res = await doFetch(url, {
+      method,
+      headers: {
+        ...token && { Authorization: `Bearer ${token}` },
+        ...body !== void 0 && !isForm && { "Content-Type": "application/json" }
+      },
+      body: body === void 0 ? void 0 : isForm ? body : JSON.stringify(body),
+      cache: "no-store"
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const err = data?.error;
+      throw new KachingError(res.status, err?.code ?? "http_error", err?.message ?? `Request failed (${res.status})`, err?.details);
+    }
+    return data;
+  }
+  const get = (path, query) => request("GET", path, void 0, query);
+  const post = (path, body) => request("POST", path, body ?? {});
+  const patch = (path, body) => request("PATCH", path, body);
+  const del = (path) => request("DELETE", path);
+  const enc = encodeURIComponent;
+  return {
+    stores: {
+      /** Requires a Clerk session token. */
+      list: () => get("/stores"),
+      /** Requires a Clerk session token. Returns API keys once. */
+      create: (input) => post("/stores", input)
+    },
+    store: {
+      get: () => get("/store"),
+      update: (input) => patch("/store", input)
+    },
+    payments: {
+      status: () => get("/store/payments"),
+      /** Creates the Stripe account if needed and returns onboarding links. */
+      onboard: (input = {}) => post("/store/payments", input)
+    },
+    products: {
+      list: (query = {}) => get("/products", query),
+      /** By id or slug. */
+      get: (idOrSlug) => get(`/products/${enc(idOrSlug)}`),
+      create: (input) => post("/products", input),
+      update: (idOrSlug, input) => patch(`/products/${enc(idOrSlug)}`, input),
+      delete: (idOrSlug) => del(`/products/${enc(idOrSlug)}`),
+      addVariant: (idOrSlug, input) => post(`/products/${enc(idOrSlug)}/variants`, input),
+      /** Uploads an image (≤4 MB) and appends it to the product. */
+      uploadImage: (idOrSlug, file, filename = "image") => {
+        const form = new FormData();
+        form.append("file", file, filename);
+        return request("POST", `/products/${enc(idOrSlug)}/images`, form);
+      }
+    },
+    variants: {
+      update: (id, input) => patch(`/variants/${enc(id)}`, input),
+      delete: (id) => del(`/variants/${enc(id)}`),
+      files: {
+        list: (variantId) => get(`/variants/${enc(variantId)}/files`),
+        /** Registers a file and uploads its bytes via the signed URL. */
+        upload: async (variantId, file, filename) => {
+          const created = await post(`/variants/${enc(variantId)}/files`, {
+            filename,
+            content_type: file.type || void 0,
+            size_bytes: file.size
+          });
+          const res = await doFetch(created.upload_url, {
+            method: "PUT",
+            headers: file.type ? { "Content-Type": file.type } : {},
+            body: file
+          });
+          if (!res.ok) throw new KachingError(res.status, "upload_failed", `File upload failed (${res.status})`);
+          const { upload_url: _, ...rest } = created;
+          return rest;
+        }
+      }
+    },
+    shippingRates: {
+      list: () => get("/shipping-rates"),
+      create: (input) => post("/shipping-rates", input),
+      update: (id, input) => patch(`/shipping-rates/${enc(id)}`, input),
+      delete: (id) => del(`/shipping-rates/${enc(id)}`)
+    },
+    carts: {
+      create: (input = {}) => post("/carts", input),
+      get: (id) => get(`/carts/${enc(id)}`),
+      /** Adds to the existing quantity. */
+      addItem: (id, item) => post(`/carts/${enc(id)}/items`, item),
+      /** Sets the quantity; 0 removes the line. */
+      updateItem: (id, variantId, quantity) => patch(`/carts/${enc(id)}/items/${enc(variantId)}`, { quantity }),
+      removeItem: (id, variantId) => del(`/carts/${enc(id)}/items/${enc(variantId)}`),
+      checkout: (id, input) => post(`/carts/${enc(id)}/checkout`, input)
+    },
+    checkout: {
+      /** "Buy now": creates a cart and a checkout in one call. */
+      create: (input) => post("/checkout", input),
+      /** The order for a completed Checkout Session. 404 until the payment webhook lands — poll briefly. */
+      getOrder: (sessionId) => get(`/checkout/sessions/${enc(sessionId)}`)
+    },
+    orders: {
+      list: (query = {}) => get("/orders", query),
+      get: (id) => get(`/orders/${enc(id)}`),
+      fulfill: (id) => post(`/orders/${enc(id)}/fulfill`)
+    }
+  };
+}
+function formatMoney(amount, currency, locale) {
+  const code = currency.toUpperCase();
+  const digits = new Intl.NumberFormat("en", { style: "currency", currency: code }).resolvedOptions().maximumFractionDigits ?? 2;
+  return new Intl.NumberFormat(locale, { style: "currency", currency: code }).format(amount / 10 ** digits);
+}
+export {
+  DEFAULT_BASE_URL,
+  KachingError,
+  createKaching,
+  formatMoney
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@kaching.sh/sdk",
+  "version": "0.1.0",
+  "description": "Typed client for the kaching commerce API",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "tsup": "^8",
+    "typescript": "^5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sventhaman/Kaching.git",
+    "directory": "packages/js"
+  },
+  "homepage": "https://kaching.sh",
+  "bugs": "https://github.com/sventhaman/Kaching/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "kaching",
+    "ecommerce",
+    "commerce",
+    "stripe",
+    "checkout",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}