@unifiedcommerce/sdk 0.1.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@unifiedcommerce/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run",
+    "sdk:generate": "bun scripts/generate-types.ts",
+    "sdk:generate:local": "bun scripts/generate-types.ts --local",
+    "sdk:generate:runvae": "bun scripts/generate-types.ts --app ../../apps/runvae",
+    "sdk:generate:store-example": "bun scripts/generate-types.ts --app ../../apps/store-example"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.17.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "*",
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "@unifiedcommerce/core": "*",
+    "@unifiedcommerce/plugin-appointments": "*",
+    "@unifiedcommerce/plugin-marketplace": "*",
+    "@unifiedcommerce/plugin-pos": "*",
+    "drizzle-orm": "^0.45.1",
+    "eslint": "^9.39.1",
+    "openapi-typescript": "^7.13.0",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "openapi-react-query": ">=0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "openapi-react-query": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,305 @@
+import createClient from "openapi-fetch";
+import type { paths } from "./generated/api-types";
+import { authMiddleware, type AuthCredential } from "./middleware";
+
+export interface SDKOptions {
+  /** Base URL of the UnifiedCommerce server (e.g., "http://localhost:4000"). */
+  baseUrl: string;
+  /** Authentication credential (API key or Bearer token). */
+  auth?: AuthCredential | undefined;
+  /** Additional headers sent with every request. */
+  headers?: Record<string, string> | undefined;
+  /** Custom fetch implementation (for testing or SSR). */
+  fetch?: typeof globalThis.fetch | undefined;
+}
+
+// Strips undefined values from params to satisfy exactOptionalPropertyTypes
+function params<T extends Record<string, unknown>>(p: T): T {
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(p)) {
+    if (v !== undefined) result[k] = v;
+  }
+  return result as T;
+}
+
+/**
+ * Creates a typed UnifiedCommerce SDK client.
+ *
+ * Layer 1 (generated types from OpenAPI spec) provides compile-time
+ * validation of request bodies, query parameters, and response shapes.
+ *
+ * Layer 2 (this wrapper) provides ergonomic domain namespaces:
+ * sdk.catalog.list(), sdk.cart.addItem(), sdk.orders.get(), etc.
+ *
+ * For routes not covered by the wrapper (plugin routes, custom routes),
+ * use sdk.raw which is the full openapi-fetch client with all paths typed.
+ */
+export function createSDK(options: SDKOptions) {
+  const clientOpts: Parameters<typeof createClient<paths>>[0] = {
+    baseUrl: options.baseUrl,
+  };
+  if (options.headers) clientOpts.headers = options.headers;
+  if (options.fetch) clientOpts.fetch = options.fetch;
+
+  const client = createClient<paths>(clientOpts);
+
+  if (options.auth) {
+    client.use(authMiddleware(options.auth));
+  }
+
+  return {
+    /** Raw openapi-fetch client for paths not covered by the wrapper. */
+    raw: client,
+
+    // ─── Catalog ──────────────────────────────────────────────────────────
+
+    catalog: {
+      list(query?: { type?: string; status?: string; category?: string; brand?: string; include?: string; sort?: string; page?: string; limit?: string }) {
+        return client.GET("/api/catalog/entities", query ? { params: { query } } : {});
+      },
+      get(idOrSlug: string, query?: { include?: string }) {
+        return client.GET("/api/catalog/entities/{idOrSlug}", { params: params({ path: { idOrSlug }, ...(query ? { query } : {}) }) });
+      },
+      create(body: paths["/api/catalog/entities"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/catalog/entities", { body });
+      },
+      update(id: string, body: paths["/api/catalog/entities/{id}"]["patch"]["requestBody"]["content"]["application/json"]) {
+        return client.PATCH("/api/catalog/entities/{id}", { params: { path: { id } }, body });
+      },
+      remove(id: string) {
+        return client.DELETE("/api/catalog/entities/{id}", { params: { path: { id } } });
+      },
+      publish(id: string) {
+        return client.POST("/api/catalog/entities/{id}/publish", { params: { path: { id } } });
+      },
+      archive(id: string) {
+        return client.POST("/api/catalog/entities/{id}/archive", { params: { path: { id } } });
+      },
+      discontinue(id: string) {
+        return client.POST("/api/catalog/entities/{id}/discontinue", { params: { path: { id } } });
+      },
+      setAttributes(id: string, locale: string, body: paths["/api/catalog/entities/{id}/attributes/{locale}"]["put"]["requestBody"]["content"]["application/json"]) {
+        return client.PUT("/api/catalog/entities/{id}/attributes/{locale}", { params: { path: { id, locale } }, body });
+      },
+      getAttributes(id: string, locale: string) {
+        return client.GET("/api/catalog/entities/{id}/attributes/{locale}", { params: { path: { id, locale } } });
+      },
+      addToCategory(id: string, categoryId: string) {
+        return client.POST("/api/catalog/entities/{id}/categories/{categoryId}", { params: { path: { id, categoryId } } });
+      },
+      removeFromCategory(id: string, categoryId: string) {
+        return client.DELETE("/api/catalog/entities/{id}/categories/{categoryId}", { params: { path: { id, categoryId } } });
+      },
+      listCategories() {
+        return client.GET("/api/catalog/categories");
+      },
+      createCategory(body: paths["/api/catalog/categories"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/catalog/categories", { body });
+      },
+      updateCategory(categoryId: string, body: paths["/api/catalog/categories/{categoryId}"]["patch"]["requestBody"]["content"]["application/json"]) {
+        return client.PATCH("/api/catalog/categories/{categoryId}", { params: { path: { categoryId } }, body });
+      },
+      deleteCategory(categoryId: string) {
+        return client.DELETE("/api/catalog/categories/{categoryId}", { params: { path: { categoryId } } });
+      },
+      listBrands() {
+        return client.GET("/api/catalog/brands");
+      },
+      createBrand(body: paths["/api/catalog/brands"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/catalog/brands", { body });
+      },
+      updateBrand(brandId: string, body: paths["/api/catalog/brands/{brandId}"]["patch"]["requestBody"]["content"]["application/json"]) {
+        return client.PATCH("/api/catalog/brands/{brandId}", { params: { path: { brandId } }, body });
+      },
+      deleteBrand(brandId: string) {
+        return client.DELETE("/api/catalog/brands/{brandId}", { params: { path: { brandId } } });
+      },
+      addToBrand(id: string, brandId: string) {
+        return client.POST("/api/catalog/entities/{id}/brands/{brandId}", { params: { path: { id, brandId } } });
+      },
+      removeFromBrand(id: string, brandId: string) {
+        return client.DELETE("/api/catalog/entities/{id}/brands/{brandId}", { params: { path: { id, brandId } } });
+      },
+      createOptionType(id: string, body: paths["/api/catalog/entities/{id}/options"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/catalog/entities/{id}/options", { params: { path: { id } }, body });
+      },
+      createOptionValue(optionTypeId: string, body: paths["/api/catalog/options/{optionTypeId}/values"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/catalog/options/{optionTypeId}/values", { params: { path: { optionTypeId } }, body });
+      },
+      createVariant(id: string, body: paths["/api/catalog/entities/{id}/variants"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/catalog/entities/{id}/variants", { params: { path: { id } }, body });
+      },
+      generateVariants(id: string, body: paths["/api/catalog/entities/{id}/variants/generate"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/catalog/entities/{id}/variants/generate", { params: { path: { id } }, body });
+      },
+    },
+
+    // ─── Inventory ────────────────────────────────────────────────────────
+
+    inventory: {
+      check(query: { entityIds: string }) {
+        return client.GET("/api/inventory/check", { params: { query } });
+      },
+      adjust(body: paths["/api/inventory/adjust"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/inventory/adjust", { body });
+      },
+      reserve(body: paths["/api/inventory/reserve"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/inventory/reserve", { body });
+      },
+      release(body: paths["/api/inventory/release"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/inventory/release", { body });
+      },
+      createWarehouse(body: paths["/api/inventory/warehouses"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/inventory/warehouses", { body });
+      },
+      listWarehouses() {
+        return client.GET("/api/inventory/warehouses");
+      },
+    },
+
+    // ─── Cart ─────────────────────────────────────────────────────────────
+
+    cart: {
+      create(body: paths["/api/carts"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/carts", { body });
+      },
+      get(id: string) {
+        return client.GET("/api/carts/{id}", { params: { path: { id } } });
+      },
+      addItem(id: string, body: paths["/api/carts/{id}/items"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/carts/{id}/items", { params: { path: { id } }, body });
+      },
+      updateItem(id: string, itemId: string, body: paths["/api/carts/{id}/items/{itemId}"]["patch"]["requestBody"]["content"]["application/json"]) {
+        return client.PATCH("/api/carts/{id}/items/{itemId}", { params: { path: { id, itemId } }, body });
+      },
+      removeItem(id: string, itemId: string) {
+        return client.DELETE("/api/carts/{id}/items/{itemId}", { params: { path: { id, itemId } } });
+      },
+    },
+
+    // ─── Checkout ─────────────────────────────────────────────────────────
+
+    checkout: {
+      create(body: paths["/api/checkout"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/checkout", { body });
+      },
+    },
+
+    // ─── Orders ───────────────────────────────────────────────────────────
+
+    orders: {
+      list(query?: { page?: string; limit?: string; status?: string }) {
+        return client.GET("/api/orders", query ? { params: { query } } : {});
+      },
+      get(idOrNumber: string) {
+        return client.GET("/api/orders/{idOrNumber}", { params: { path: { idOrNumber } } });
+      },
+      changeStatus(id: string, body: paths["/api/orders/{id}/status"]["patch"]["requestBody"]["content"]["application/json"]) {
+        return client.PATCH("/api/orders/{id}/status", { params: { path: { id } }, body });
+      },
+      listFulfillments(id: string) {
+        return client.GET("/api/orders/{id}/fulfillments", { params: { path: { id } } });
+      },
+    },
+
+    // ─── Pricing ──────────────────────────────────────────────────────────
+
+    pricing: {
+      setBasePrice(body: paths["/api/pricing/prices"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/pricing/prices", { body });
+      },
+      listPrices(query?: { entityId?: string; variantId?: string; currency?: string }) {
+        return client.GET("/api/pricing/prices", query ? { params: { query } } : {});
+      },
+      createModifier(body: paths["/api/pricing/modifiers"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/pricing/modifiers", { body });
+      },
+    },
+
+    // ─── Promotions ───────────────────────────────────────────────────────
+
+    promotions: {
+      create(body: paths["/api/promotions"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/promotions", { body });
+      },
+      list() {
+        return client.GET("/api/promotions");
+      },
+      validate(body: paths["/api/promotions/validate"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/promotions/validate", { body });
+      },
+      deactivate(id: string) {
+        return client.POST("/api/promotions/{id}/deactivate", { params: { path: { id } } });
+      },
+    },
+
+    // ─── Search ───────────────────────────────────────────────────────────
+
+    search: {
+      query(query: { q: string; type?: string; page?: string; limit?: string }) {
+        return client.GET("/api/search", { params: { query } });
+      },
+      suggest(query: { prefix: string; type?: string; limit?: string }) {
+        return client.GET("/api/search/suggest", { params: { query } });
+      },
+    },
+
+    // ─── Webhooks ─────────────────────────────────────────────────────────
+
+    webhooks: {
+      create(body: paths["/api/webhooks"]["post"]["requestBody"]["content"]["application/json"]) {
+        return client.POST("/api/webhooks", { body });
+      },
+      list() {
+        return client.GET("/api/webhooks");
+      },
+      remove(id: string) {
+        return client.DELETE("/api/webhooks/{id}", { params: { path: { id } } });
+      },
+    },
+
+    // ─── Customer Self-Service (me) ───────────────────────────────────────
+
+    me: {
+      profile: {
+        get() { return client.GET("/api/me/profile"); },
+        update(body: paths["/api/me/profile"]["patch"]["requestBody"]["content"]["application/json"]) {
+          return client.PATCH("/api/me/profile", { body });
+        },
+      },
+      addresses: {
+        list() { return client.GET("/api/me/addresses"); },
+        create(body: paths["/api/me/addresses"]["post"]["requestBody"]["content"]["application/json"]) {
+          return client.POST("/api/me/addresses", { body });
+        },
+        remove(id: string) {
+          return client.DELETE("/api/me/addresses/{id}", { params: { path: { id } } });
+        },
+      },
+      orders: {
+        list(query?: { page?: string; limit?: string }) {
+          return client.GET("/api/me/orders", query ? { params: { query } } : {});
+        },
+        // idOrNumber: accepts UUID or order number (e.g., "ORD-001")
+        get(idOrNumber: string) {
+          return client.GET("/api/me/orders/{idOrNumber}", { params: { path: { idOrNumber } } });
+        },
+        // idOrNumber: accepts UUID or order number
+        tracking(idOrNumber: string) {
+          return client.GET("/api/me/orders/{idOrNumber}/tracking", { params: { path: { idOrNumber } } });
+        },
+        // orderId: UUID only (downloads are keyed by internal ID, not order number)
+        downloads(orderId: string) {
+          return client.GET("/api/me/orders/{orderId}/downloads", { params: { path: { orderId } } });
+        },
+        // orderId: UUID only
+        reorder(orderId: string) {
+          return client.POST("/api/me/orders/{orderId}/reorder", { params: { path: { orderId } } });
+        },
+      },
+      courses: {
+        list() { return client.GET("/api/me/courses"); },
+      },
+    },
+  };
+}