@cronvello/shop-sdk 0.1.0

package/CONTRACT_SHA256

@@ -0,0 +1 @@
+335eed391a2786a4f7f010b056d2a6a5b49d9e1244960a15516a5d77b93693b5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niccas Williams
+
+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,128 @@
+# @cronvello/shop-sdk
+
+The shared, typed integration layer for node-shop. It gives Node.js backends and Next.js apps the
+same versioned API contract and the same request behavior instead of copying generated files or
+maintaining one wrapper per application.
+
+- Zero runtime dependencies, ESM and CommonJS, Node 20+
+- Complete generated node-shop types and route catalog
+- Strongly typed path parameters, query values, bodies, and response data
+- Production URL built in, with explicit override or an async URL resolver
+- Server and browser entry points with different secret-safety defaults
+- Timeout, cancellation, bounded safe-method retries, envelope handling, and structured errors
+
+## Install
+
+```bash
+npm install @cronvello/shop-sdk
+```
+
+The initial `0.1.0` repository is configured as a private npm package (`restricted`). Only the npm
+owner and explicitly granted collaborators can see or install it.
+
+## Node.js or a Next.js server
+
+```ts
+import { createShopServerClient } from "@cronvello/shop-sdk/server";
+
+const shop = createShopServerClient({
+  apiKey: process.env.NODE_SHOP_B2B_API_KEY,
+});
+
+const checkout = await shop.request("b2b_create_checkout_session", {
+  body: {
+    appId: "my-app",
+    lineItems: [{
+      name: "Pro",
+      unitAmountCents: 1900,
+      currency: "eur",
+      quantity: 1,
+      recurring: { interval: "month" },
+    }],
+    successUrl: "https://example.com/success",
+    cancelUrl: "https://example.com/cancel",
+  },
+});
+```
+
+`createShopServerClientFromEnv()` reads `NODE_SHOP_URL`, `NODE_SHOP_B2B_API_KEY`, and
+`NODE_SHOP_CRON_SECRET`. `NODE_SHOP_URL` is optional: the SDK defaults to the current production
+endpoint. For infrastructure that keeps the live URL in a database, pass an async resolver:
+
+```ts
+const shop = createShopServerClient({
+  baseUrl: () => resolveLiveServiceUrl("node-shop"),
+  apiKey: () => secrets.get("node-shop"),
+});
+```
+
+The server adapter selects headers from each generated route's auth metadata. B2B routes receive
+both the current `x-api-key` header and the legacy Bearer form used by some node-shop middleware.
+Frontend JWT and cron routes use separate `frontendToken` and `cronSecret` providers. Composite
+auth routes can be handled with the `headers(context)` callback.
+
+## Next.js client components or another browser
+
+```ts
+import { createShopBrowserClient } from "@cronvello/shop-sdk/browser";
+
+const shop = createShopBrowserClient({
+  headers: { "x-public-api-key": publicStorefrontKey },
+});
+
+const result = await shop.request("products_public_search", {
+  query: { query: "shirt", page: 1 },
+});
+```
+
+The browser adapter rejects non-public routes by default so a backend secret is not accidentally
+shipped to a client bundle. Set `allowAuthenticatedRoutes` only when a short-lived user credential
+is intentionally supplied by your application.
+
+## Contract-only imports
+
+```ts
+import { apiRoutes, type Product, type ApiRouteKey } from "@cronvello/shop-sdk/contract";
+```
+
+The raw OpenAPI document is exported as `@cronvello/shop-sdk/openapi.json`.
+
+## Errors and retries
+
+Failed HTTP responses and successful HTTP envelopes with `success: false` throw `ShopApiError`.
+It contains status, route key, method, path, request ID, and the parsed response body, but never
+stores credentials. GET/HEAD/OPTIONS requests retry transient statuses twice by default with
+bounded exponential backoff. Mutations are never retried unless `retryUnsafe: true` is set for a
+known-idempotent call.
+
+```ts
+import { ShopApiError } from "@cronvello/shop-sdk";
+
+try {
+  await shop.request("products_public_search", { query: { page: 1 } });
+} catch (error) {
+  if (error instanceof ShopApiError) {
+    console.error(error.status, error.routeKey, error.requestId);
+  }
+}
+```
+
+## Updating the contract
+
+node-shop remains the producer. From this repository, after regenerating node-shop's contract:
+
+```bash
+npm run sync:contract
+npm run check
+```
+
+`sync:contract` copies only the generated contract snapshot, refuses incomplete input, and records
+its SHA-256 in `CONTRACT_SHA256`. CI builds, tests, checks coverage, and verifies the exact package
+archive. `npm run sync:contract:check` detects drift against a sibling `node-shop` checkout.
+
+## Publishing
+
+Publication is tag-driven, matching the CronVello SDK pattern. Bump `package.json`, push the commit,
+then push `vX.Y.Z`. The workflow verifies the tag and package versions before using npm trusted
+publishing with `restricted` access. A manual workflow run performs a dry-run only. Private npm
+packages require a paid npm user or organization account.