@k9o/gate 0.0.0-stage → 1.0.0

package/src/client-factory.ts

@@ -0,0 +1,39 @@
+/**
+ * `createGateClient(config)` — per-instance Gate SDK factory (v0.4.0).
+ *
+ * Returns a self-contained `GateClient` that does not depend on the
+ * module-level `configureGate()` singleton. Multiple clients can coexist
+ * in the same process, each scoped to its own project + baseUrl + mode —
+ * useful for multi-tenant Backends-For-Frontends (one client per
+ * incoming request's resolved tenant) or for apps that maintain both a
+ * Standalone and Native binding against the same SDK instance.
+ *
+ * Per v2.5.68 URL grammar, supply `projectSlug` for
+ * canonical `/@<slug>/gate/...` routing. Slug is the only customer-facing
+ * project addressing form — project ids are internal-only
+ * (`feedback_slug_addressing_v2_5_68`); the retired `/v2/projects/...`
+ * mounts were dropped at pass17 (`feedback_v2_path_is_an_error`).
+ *
+ * Example:
+ *   const client = createGateClient({
+ *     baseUrl: 'https://formelo.api.k9o.io',
+ *     projectSlug: 'partner-console-staging',
+ *     mode: 'native',
+ *   });
+ *   await client.signIn({ email, password });
+ */
+
+import { makeGateNamespace } from "./gate.ts";
+import { validateGateConfig, type GateConfig } from "./mode.ts";
+
+/** Shape of the per-instance client returned by `createGateClient`. */
+export type GateClient = ReturnType<typeof makeGateNamespace>;
+
+/** Construct a Gate client bound to the supplied config. The config is
+ *  validated up-front and stored on the instance; subsequent calls do not
+ *  re-read process-level state. Throws `TypeError` on invalid config. */
+export function createGateClient(config: GateConfig): GateClient {
+  validateGateConfig(config);
+  const frozen: GateConfig = { ...config };
+  return makeGateNamespace(() => frozen);
+}

package/src/client.ts

@@ -0,0 +1,175 @@
+/**
+ * HTTP client abstraction for the Gate SDK.
+ *
+ * Centralises:
+ *   - URL construction against the configured `baseUrl` + per-call path
+ *   - the standard ch01 §1 envelope unwrap on success
+ *   - the standard ch01 §2 `KError` rehydration on failure via `gateErrorFromWire`
+ *   - mode-routing via the `X-Gate-Mode` header (so the gateway routes
+ *     consumption to the right billing surface without per-function
+ *     branching at the SDK)
+ *
+ * Customers don't reach for this directly; it's the internal client
+ * every `gate.*` function consumes. `request`/`requestWith` are
+ * module-internal only — neither `index.ts` nor the `package.json`
+ * `exports` map re-exports them, so they are not part of the public
+ * `@k9o/gate` surface. In-package `gate.*` bindings and the test suite
+ * import them from this module directly.
+ */
+
+import { getGateConfig, type GateConfig } from "./mode.ts";
+import { resolveRegionalOrigin } from "./region.ts";
+import { GateError, type KErrorWire, gateErrorFromWire } from "./errors.ts";
+import type { Envelope } from "./types.ts";
+
+export type RequestInit = {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  /** Optional JSON body — serialised by the client. */
+  body?: unknown;
+  /** Optional per-call bearer token. Falls back to `partnerToken` from config when omitted. */
+  bearerToken?: string;
+  /** Optional additional headers; merged with the defaults. */
+  headers?: Record<string, string>;
+  /** Optional query parameters. */
+  query?: Record<string, string | number | boolean | undefined>;
+};
+
+/**
+ * Issue a request against the Gate API. Returns the unwrapped envelope
+ * data on 2xx; throws a `GateError` carrying the closed-taxonomy `code`
+ * + structured `context` on non-2xx.
+ *
+ * Implementation notes:
+ *   - The function pulls config lazily so `configureGate()` order doesn't
+ *     have to predate import-time module evaluation.
+ *   - `fetch` is taken from config when set, else from the global; this
+ *     keeps the SDK portable across Bun + Node 18+ + browsers + test
+ *     fixtures that supply a stub.
+ *   - JSON parsing of non-JSON responses throws — gateway always returns
+ *     JSON per ch01 §1 + §2, so a parse failure is an upstream defect.
+ */
+export async function request<T>(init: RequestInit): Promise<Envelope<T>> {
+  return requestWith<T>(getGateConfig(), init);
+}
+
+/**
+ * Issue a request using an explicit config (used by per-instance clients
+ * returned from `createGateClient`). Singleton callers reach for
+ * `request()` which delegates here against the module-level config.
+ */
+export async function requestWith<T>(
+  config: GateConfig,
+  init: RequestInit,
+): Promise<Envelope<T>> {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new GateError({
+      code: "INTERNAL_ERROR",
+      message:
+        "No fetch implementation available — configure {fetch} in configureGate() for non-browser, non-Bun, non-Node-18+ environments",
+      context: {},
+      recommendation: null,
+    });
+  }
+
+  const url = buildUrl(await resolveRegionalOrigin(config), init.path, init.query);
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    "x-gate-mode": config.mode,
+    ...(init.headers ?? {}),
+  };
+  const bearer = init.bearerToken ?? config.partnerToken;
+  if (typeof bearer === "string" && bearer.length > 0) {
+    headers["authorization"] = `Bearer ${bearer}`;
+  }
+  const requestInit: Record<string, unknown> = {
+    method: init.method,
+    headers,
+  };
+  if (init.body !== undefined) {
+    headers["content-type"] = "application/json";
+    requestInit["body"] = JSON.stringify(init.body);
+  }
+
+  let response: Response;
+  try {
+    response = await fetchImpl(url, requestInit as Parameters<typeof fetchImpl>[1]);
+  } catch (e) {
+    throw new GateError({
+      code: "UPSTREAM_UNAVAILABLE",
+      message: `Network error reaching ${url}: ${e instanceof Error ? e.message : String(e)}`,
+      context: { url },
+      recommendation: null,
+    });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = await response.json();
+  } catch (e) {
+    throw new GateError({
+      code: "INTERNAL_ERROR",
+      message: `Failed to parse JSON response from ${url}: ${e instanceof Error ? e.message : String(e)}`,
+      context: { url, status: response.status },
+      recommendation: null,
+      status: response.status,
+    });
+  }
+
+  if (response.status >= 200 && response.status < 300) {
+    if (!isEnvelope<T>(parsed)) {
+      throw new GateError({
+        code: "INTERNAL_ERROR",
+        message: `Malformed envelope from ${url}: expected {data, meta}`,
+        context: { url, status: response.status },
+        recommendation: null,
+        status: response.status,
+      });
+    }
+    return parsed;
+  }
+
+  // Non-2xx: the gateway returns a KError-shaped JSON payload per ch01 §2.
+  if (isKErrorWire(parsed)) {
+    throw gateErrorFromWire(parsed, response.status);
+  }
+  throw new GateError({
+    code: "INTERNAL_ERROR",
+    message: `Upstream returned ${response.status} with non-KError body`,
+    context: { url, status: response.status, body: parsed },
+    recommendation: null,
+    status: response.status,
+  });
+}
+
+function buildUrl(
+  baseUrl: string,
+  path: string,
+  query: RequestInit["query"],
+): string {
+  const trimmedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const trimmedPath = path.startsWith("/") ? path : `/${path}`;
+  let url = `${trimmedBase}${trimmedPath}`;
+  if (query !== undefined) {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined) params.set(k, String(v));
+    }
+    const qs = params.toString();
+    if (qs.length > 0) url += `?${qs}`;
+  }
+  return url;
+}
+
+function isEnvelope<T>(value: unknown): value is Envelope<T> {
+  if (value === null || typeof value !== "object") return false;
+  const v = value as { data?: unknown; meta?: unknown };
+  return "data" in v && "meta" in v && typeof v.meta === "object" && v.meta !== null;
+}
+
+function isKErrorWire(value: unknown): value is KErrorWire {
+  if (value === null || typeof value !== "object") return false;
+  const v = value as { code?: unknown; message?: unknown };
+  return typeof v.code === "string" && typeof v.message === "string";
+}

package/src/errors.ts

@@ -0,0 +1,117 @@
+/**
+ * Gate error shapes. `GateError` is `KError`-compatible per ch01 §2 —
+ * downstream catch blocks can `instanceof GateError`-narrow without
+ * importing the gateway's `KError` class directly (the SDK is a customer-
+ * facing dependency; reaching across to the gateway's internal error
+ * type would be a layering violation).
+ *
+ * The taxonomy below is the v0.1.0 closed set; additions follow the
+ * ch11 error-catalogue freeze cycle.
+ */
+
+/**
+ * Closed-taxonomy error code per ch01 §2. Strings are the wire format —
+ * camelCase-cased KError families per the convention.
+ */
+export type GateErrorCode =
+  | "UNAUTHENTICATED"
+  | "INVALID_FIELD_VALUE"
+  | "EMAIL_ALREADY_REGISTERED"
+  | "INVALID_CREDENTIALS"
+  | "SESSION_EXPIRED"
+  | "REFRESH_TOKEN_INVALID"
+  | "TIER_FEATURE_GATED"
+  | "RBAC_DENY"
+  // FORBIDDEN + NOT_FOUND added at v0.3.0 — surfaced by the
+  // gate.idpProviders.* sub-namespaces (project-membership gate +
+  // resource-existence checks per gateway v2.5.57 RBAC + NOT_FOUND
+  // paths).
+  | "FORBIDDEN"
+  | "NOT_FOUND"
+  // GATE_REDIRECT_NOT_ALLOWED — magic-link `redirectUrl` not in the project's
+  // redirect allowlist (open-redirect-safe exact-match, per-project
+  // allowlist capability).
+  | "GATE_REDIRECT_NOT_ALLOWED"
+  | "POLICY_AUTHORING_AUTHORITY_INSUFFICIENT"
+  | "UPSTREAM_UNAVAILABLE"
+  | "INTERNAL_ERROR";
+
+/**
+ * Surface error thrown by the SDK. Mirrors the gateway's `KError` shape
+ * per ch01 §2.1 — `code` (closed taxonomy), `message` (human-readable),
+ * `context` (structured per-code payload), `recommendation` (action the
+ * caller can take, or null when there's no canonical recommendation).
+ */
+export class GateError extends Error {
+  readonly code: GateErrorCode;
+  readonly context: Readonly<Record<string, unknown>>;
+  readonly recommendation: string | null;
+  /** HTTP status the gateway returned (if the error came from a wire response). */
+  readonly status: number | null;
+
+  constructor(init: {
+    code: GateErrorCode;
+    message: string;
+    context?: Record<string, unknown>;
+    recommendation?: string | null;
+    status?: number | null;
+  }) {
+    super(init.message);
+    this.name = "GateError";
+    this.code = init.code;
+    this.context = Object.freeze({ ...(init.context ?? {}) });
+    this.recommendation = init.recommendation ?? null;
+    this.status = init.status ?? null;
+  }
+}
+
+/**
+ * Wire-shape sentinel matching the gateway's `KError` JSON payload. The
+ * client uses this to recognise gateway responses and rehydrate them
+ * into a `GateError` instance with the right code + context preserved.
+ */
+export type KErrorWire = {
+  code: string;
+  message: string;
+  context?: Record<string, unknown>;
+  recommendation?: string | null;
+};
+
+/**
+ * Narrow a wire `KError` to a strongly-typed `GateError`. Unknown codes
+ * pass through as `INTERNAL_ERROR` with the original code preserved in
+ * `context.originalCode` so consumers don't lose telemetry when the
+ * server-side taxonomy outpaces the SDK's bundled enum.
+ */
+export function gateErrorFromWire(wire: KErrorWire, status: number): GateError {
+  const knownCodes: ReadonlyArray<GateErrorCode> = [
+    "UNAUTHENTICATED",
+    "INVALID_FIELD_VALUE",
+    "EMAIL_ALREADY_REGISTERED",
+    "INVALID_CREDENTIALS",
+    "SESSION_EXPIRED",
+    "REFRESH_TOKEN_INVALID",
+    "TIER_FEATURE_GATED",
+    "RBAC_DENY",
+    "FORBIDDEN",
+    "NOT_FOUND",
+    "GATE_REDIRECT_NOT_ALLOWED",
+    "POLICY_AUTHORING_AUTHORITY_INSUFFICIENT",
+    "UPSTREAM_UNAVAILABLE",
+    "INTERNAL_ERROR",
+  ];
+  // Wire codes are platform-namespaced (`K9O_*` per the ch11 error namespace);
+  // strip the prefix to match the SDK's bundled bare-code enum. The full wire
+  // code is always preserved in `context.originalCode` for telemetry.
+  const stripped = wire.code.replace(/^K9O_/, "");
+  const isKnown = (knownCodes as ReadonlyArray<string>).includes(stripped);
+  const code: GateErrorCode = isKnown ? (stripped as GateErrorCode) : "INTERNAL_ERROR";
+  const context = { ...(wire.context ?? {}), originalCode: wire.code };
+  return new GateError({
+    code,
+    message: wire.message,
+    context,
+    recommendation: wire.recommendation ?? null,
+    status,
+  });
+}