@neetru/sdk 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -7,12 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Planned (post-1.0)
+### Planned (post-1.1)
 - Telemetry batching + flush on unload.
 - LRU cache em entitlements.check (TTL configurável).
 - size-limit budget no CI (<12KB gz core com db namespace).
 - CDN distribution (`cdn.neetru.com/sdk/v1/`).
 
+## [1.1.0] - 2026-05-08 — **Checkout namespace + React helpers**
+
+Adiciona o namespace `client.checkout` (start/get/cancel intent) com auto-redirect
+em browser. Suporte ao fluxo Sprint 13 onde produtos SaaS delegam checkout pro
+portal `minhaconta.neetru.com` via `POST /api/v1/checkout/intents`.
+
+### Added
+- **`client.checkout.start({productId, planId, callbackUrl, tenantType?, tenantId?})`** — cria
+  `checkout_intents/{intentId}` no Core e (em browser) redireciona automaticamente
+  pra `minhaconta.neetru.com/portal/checkout/{intentId}`. Em Node/SSR retorna
+  `{intentId, redirectUrl}` sem efeito colateral.
+- **`client.checkout.get(intentId)`** — lê estado atual do intent.
+- **`client.checkout.cancel(intentId)`** — marca intent como `cancelled`.
+- **Subpath `@neetru/sdk/react`** — componente `<CheckoutLink>` (wrapper de `<a>`
+  que dispara `start()` no click) + `<EntitlementGate mode="block|readonly">`
+  + hook `useEntitlementContext()` pra desabilitar escritas quando free tier
+  estoura limite (decisão CEO §5 — read-only sempre, não hard-block).
+- **`MockCheckout`** — implementação dev (`NEETRU_ENV=dev`) sem network. Retorna
+  URL fake `https://localhost:9003/portal/checkout/{intentId}` pra dev externo
+  testar UI sem provisionar conta Neetru.
+- **Peer dep `react ^18 || ^19`** marcado opcional (só carregado se import `/react`).
+
+### Changed
+- `VERSION` const bump `1.0.0 → 1.1.0`.
+- `NeetruClient.checkout` adicionado — backward-compatible (caller que não usa
+  o namespace não é afetado).
+
+### Notes
+- API stability test (`api-surface-stability.test.ts`) atualizado pra incluir
+  `checkout` no inventário canônico.
+
 ## [1.0.0] - 2026-05-06 — **GA (General Availability)**
 
 Marco de estabilidade. A partir desta versão, **a superfície pública do SDK

package/dist/auth.cjs

@@ -692,6 +692,181 @@ function createDbNamespace(config) {
   };
 }
 
+// src/checkout.ts
+function parseStartResponse(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new NeetruError("invalid_response", "checkout.start response is not an object");
+  }
+  const r = raw;
+  if (typeof r.intentId !== "string" || !r.intentId) {
+    throw new NeetruError("invalid_response", "checkout.start response missing intentId");
+  }
+  if (typeof r.redirectUrl !== "string" || !r.redirectUrl) {
+    throw new NeetruError("invalid_response", "checkout.start response missing redirectUrl");
+  }
+  return {
+    intentId: r.intentId,
+    redirectUrl: r.redirectUrl,
+    status: r.status ?? "pending",
+    expiresAt: typeof r.expiresAt === "string" ? r.expiresAt : (/* @__PURE__ */ new Date()).toISOString(),
+    requiresKyc: r.requiresKyc === true
+  };
+}
+function parseGetResponse(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new NeetruError("invalid_response", "checkout.get response is not an object");
+  }
+  const r = raw;
+  const intent = r.intent;
+  if (!intent || typeof intent !== "object") {
+    throw new NeetruError("invalid_response", "checkout.get response missing intent");
+  }
+  if (typeof intent.intentId !== "string") {
+    throw new NeetruError("invalid_response", "checkout.get response missing intentId");
+  }
+  return {
+    intentId: intent.intentId,
+    uid: intent.uid ?? "",
+    targetTenantId: intent.targetTenantId ?? "",
+    targetTenantType: intent.targetTenantType ?? "pf",
+    productId: intent.productId ?? "",
+    planId: intent.planId ?? "",
+    callbackUrl: intent.callbackUrl ?? "",
+    status: intent.status ?? "pending",
+    stripeSessionId: intent.stripeSessionId ?? null,
+    expiresAt: intent.expiresAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    isStale: r.isStale === true
+  };
+}
+function inBrowser() {
+  try {
+    return typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined" && typeof globalThis.location !== "undefined" && typeof globalThis.location.assign === "function";
+  } catch {
+    return false;
+  }
+}
+function performRedirect(url) {
+  try {
+    globalThis.location.assign(url);
+  } catch {
+  }
+}
+function createHttpCheckoutNamespace(config) {
+  return {
+    async start(input) {
+      if (!input?.productId) {
+        throw new NeetruError("validation_failed", "checkout.start: productId is required");
+      }
+      if (!input?.planId) {
+        throw new NeetruError("validation_failed", "checkout.start: planId is required");
+      }
+      if (!input?.callbackUrl) {
+        throw new NeetruError("validation_failed", "checkout.start: callbackUrl is required");
+      }
+      const body = {
+        productId: input.productId,
+        planId: input.planId,
+        callbackUrl: input.callbackUrl
+      };
+      if (input.tenantType) body.targetTenantType = input.tenantType;
+      if (input.tenantId) body.targetTenantId = input.tenantId;
+      const raw = await httpRequest(config, {
+        method: "POST",
+        path: "/api/v1/checkout/intents",
+        body,
+        requireAuth: true
+      });
+      const result = parseStartResponse(raw);
+      const shouldRedirect = input.autoRedirect !== false;
+      if (shouldRedirect && inBrowser()) {
+        performRedirect(result.redirectUrl);
+      }
+      return result;
+    },
+    async get(intentId) {
+      if (!intentId || typeof intentId !== "string") {
+        throw new NeetruError("validation_failed", "checkout.get: intentId is required");
+      }
+      const raw = await httpRequest(config, {
+        method: "GET",
+        path: `/api/v1/checkout/intents/${encodeURIComponent(intentId)}`,
+        requireAuth: true
+      });
+      return parseGetResponse(raw);
+    },
+    async cancel(intentId) {
+      if (!intentId || typeof intentId !== "string") {
+        throw new NeetruError("validation_failed", "checkout.cancel: intentId is required");
+      }
+      const raw = await httpRequest(config, {
+        method: "DELETE",
+        path: `/api/v1/checkout/intents/${encodeURIComponent(intentId)}`,
+        requireAuth: true
+      });
+      return {
+        ok: true,
+        alreadyCancelled: raw?.alreadyCancelled === true
+      };
+    }
+  };
+}
+var MockCheckout = class {
+  intents = /* @__PURE__ */ new Map();
+  async start(input) {
+    if (!input?.productId) {
+      throw new NeetruError("validation_failed", "checkout.start: productId is required");
+    }
+    if (!input?.planId) {
+      throw new NeetruError("validation_failed", "checkout.start: planId is required");
+    }
+    if (!input?.callbackUrl) {
+      throw new NeetruError("validation_failed", "checkout.start: callbackUrl is required");
+    }
+    const intentId = `chk_mock_${Math.random().toString(36).slice(2, 10)}`;
+    const expiresAt = new Date(Date.now() + 15 * 60 * 1e3).toISOString();
+    const redirectUrl = `https://localhost:9003/portal/checkout/${intentId}`;
+    this.intents.set(intentId, {
+      intentId,
+      uid: "dev-fixture-uid",
+      targetTenantId: input.tenantId ?? "dev-fixture-uid",
+      targetTenantType: input.tenantType ?? "pf",
+      productId: input.productId,
+      planId: input.planId,
+      callbackUrl: input.callbackUrl,
+      status: "pending",
+      stripeSessionId: null,
+      expiresAt
+    });
+    return {
+      intentId,
+      redirectUrl,
+      status: "pending",
+      expiresAt,
+      requiresKyc: false
+    };
+  }
+  async get(intentId) {
+    const found = this.intents.get(intentId);
+    if (!found) {
+      throw new NeetruError("not_found", `Mock intent ${intentId} not found`);
+    }
+    return { ...found };
+  }
+  async cancel(intentId) {
+    const found = this.intents.get(intentId);
+    if (!found) {
+      throw new NeetruError("not_found", `Mock intent ${intentId} not found`);
+    }
+    const alreadyCancelled = found.status === "cancelled";
+    this.intents.set(intentId, { ...found, status: "cancelled" });
+    return { ok: true, alreadyCancelled };
+  }
+};
+function createCheckoutNamespace(config) {
+  if (config.env === "dev") return new MockCheckout();
+  return createHttpCheckoutNamespace(config);
+}
+
 // src/mocks.ts
 var DEV_FIXTURE_USER = Object.freeze({
   uid: "dev-fixture-uid-0001",
@@ -1127,7 +1302,8 @@ function createNeetruClient(config = {}) {
     telemetry: createTelemetryNamespace(resolved),
     usage,
     support,
-    db
+    db,
+    checkout: createCheckoutNamespace(resolved)
   });
   return client;
 }