@k9o/core 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog — @k9o/core
+
+## Unreleased
+
+- NEW `client.storage.locations.{list, create, get, update, retire, test}` — storage locations over `/@<projectSlug>/storage/locations`: register your own object store once per project from a pre-created `credentialRef`, then link it to buckets and Datasets. Provider-specific ids (`accountId` and `parentAccessKeyId` for r2, `bucketId` for b2) go in `providerParams`. New types: `StorageLocation`, `CreateStorageLocationInput`, `UpdateStorageLocationInput`, `StorageLocationProviderParams` and friends.
+- REMOVED (breaking) `client.byos.{list, create, get}` and the types `ByosBinding`, `CreateByosBindingInput`, `ByosProvider`, `ByosCustodyMode`, `ByosPurpose`. The purpose-based `/@<projectSlug>/byos` routes are withdrawn and answer 404; a location has no purpose. The credential helpers in `@k9o/core/byos` are unchanged.
+- REMOVED `client.policies.deactivate()` — the emergency-deactivate verb is retired per ch06 §9.4.4; use the publish-lockdown pattern instead.
+
+## v0.5.0 — 2026-05-25 (org-plane + operator-self namespaces)
+
+NEW `client.org.*` org-plane namespace + NEW `client.me.*` operator-self namespace.
+
+- `client.org.members.{list, invite, get, remove}` per ch02 §6 + ask 1
+- `client.org.groups.{list, create, get, delete}` per ch02 §6 + ask 2
+- `client.org.auditLog.{query, tail}` per ch05 §4.4 + 6-event org family per ch05 §4.2 + ask 3 (distinct from project-plane `client.audit`)
+- `client.org.gate.roles.{list, grant, get, revoke}` per ch02 §6.5 `_sys.org_role_grants` substrate + ask 4 (ORG_ADMIN / ORG_BILLING_ADMIN grants with soft-delete revocation)
+- `client.org.gate.idpProviders.{list, create, get, configure, delete}` per ch02 §6.5 + ask 7
+- `client.org.smtp.{get, set, test, unset}` per ch02 §6.6 + ask 5 (3-tier cascade platform→org→project; Kibo-enclave password sequestration; 5/hour test-email rate limit)
+- `client.org.get()` — read bound org (mirrors `client.orgs.current()` for namespace symmetry)
+- `client.me.profile.{get, update}` — operator profile per ch01 §5.4 `/me/*` cross-org canonical
+- `client.me.sessions.{list, revoke, revokeAll}` — operator session management
+- `client.me.apiTokens.{list, create, delete}` — personal scripting tokens (forward substrate)
+- `client.me.notifications.{list, markRead, markAllRead}` — operator-targeted notifications (forward substrate)
+- `client.me.auditLog.query()` — operator-self audit (actions performed BY this operator across orgs; distinct from project-plane + org-plane audit)
+- `client.me.dataExport.{request, status}` — personal data export per GDPR-style flows (forward substrate)
+
+27 new tests pass / 0 fail covering URL composition across all org-plane + me-plane methods. Total @k9o/core suite: 124 / 0 across 8 test files.
+
+## v0.4.0 — 2026-05-25 (checkpoint D — retry + backoff)
+
+- HTTP client now retries transient failures per `retryConfig: { maxRetries, backoff: "exponential" | "linear" | "none", initialDelayMs, maxDelayMs }`
+- `createClient({ retryConfig: ... })` threads the config into the bound HTTP layer
+- Retryable: transport failures (`K9O_UPSTREAM_UNAVAILABLE`); HTTP 502/503/504; HTTP 429 (rate-limit)
+- Non-retryable: other 4xx (caller error); other 5xx (gateway-side bug; surface immediately); non-KError thrown values
+- Idempotency gate: only GET / HEAD / OPTIONS / DELETE are retried. POST / PATCH / PUT are never retried automatically — callers can opt in via `idempotencyKey` header per ch01 §10.2 when they assert idempotency (future sub-cycle integrates the header-driven path)
+- Backoff: exponential default (initialDelayMs * 2^attempt, capped, ±25% jitter); linear available; none for tight loops; defaults 100ms initial / 5000ms cap / 3 retries
+- 19 new tests covering isRetryable predicate + computeDelay backoff variants + withRetry orchestration + end-to-end HTTP retry integration. Total @k9o/core suite: 97 pass / 0 fail.
+
+## v0.3.0 — 2026-05-25 (checkpoint C — pillar composition: `client.gate` + `client.extensions`)
+
+- `client.gate` composed from `@k9o/gate` via gate-bridge — shares baseUrl + projectSlug; mode defaults to `native`; partnerToken inherits from apiKey. Throws `K9O_MISSING_PROJECT_CONTEXT` when accessed without projectSlug bound.
+- `client.extensions` composed from `@k9o/extensions` — `client.extensions.extension(slug)` factory returning typed Trailblazer/Anchor/Keystone class extension bindings per ch13 §8.1.
+- `@k9o/gate` + `@k9o/extensions` added as workspace dependencies.
+- 6 new composition tests pass: gate namespace exposed when projectSlug bound; gate throws K9O_MISSING_PROJECT_CONTEXT without it; gate routes against same baseUrl + projectSlug as K9oClient; extensions.extension factory + paperless + cairn binding types resolve.
+- KError ↔ GateError alignment is still open. Until then both error types are shape-compatible; caller code narrowing on `.code` works against either.
+- Total @k9o/core suite: 78 pass / 0 fail across 6 test files.
+
+## v0.2.0 — 2026-05-25 (checkpoint B — migrations + functions + policies + audit + orgs)
+
+5 new namespaces wired to gateway routes:
+
+- `client.migrations` — apply / list / get / queue / listPending / applyPending / rejectPending / deletePending per ch04 §2 + gateway `routes/migrations.ts` (8 methods)
+- `client.functions` — deploy / list / get / delete / invoke per ch07 + gateway `routes/{functions,invoke}.ts` (5 methods)
+- `client.policies` — current / list / create / validate / get / update / delete / publish / deactivate per ch06 §9 + gateway `routes/policies.ts` (9 methods)
+- `client.audit` — query / tail per ch05 §4 + gateway `routes/audit-log.ts` (2 methods)
+- `client.orgs` — list / get / restore / current per ch02 + gateway `routes/orgs-crud.ts` (4 methods)
+
+20 new unit tests pass / 0 fail (covers URL composition + HTTP method + body shape + query string serialisation across all 5 namespaces). Total @k9o/core suite: 72 pass.
+
+Forward sub-cycles: pillar composition (client.gate + client.extensions re-exports), retry/backoff in HTTP client, subscription/streaming, kibo namespace (composes with future @k9o/kibo).
+
+## v0.1.0 — 2026-05-25 (first-pass scaffold)
+
+NEW package. Surfaces shipped:
+
+- `createClient(options)` factory with baseUrl validation
+- HTTP client (`request`) with envelope unwrap on 2xx + `KError` rehydration on non-2xx + bearer/project/org header injection + transport failure mapping per ch01 §1 + §2
+- `KError` class + `KErrorWire` type + `kerrorFromWire` rehydration per ch01 §2 + ch11
+- Envelope + meta accessor types (`Envelope<T>` / `MetaCursor` / `MetaSubscription` / `MetaIdempotency` / `MetaWarning` / `MetaCost` / `MetaTiming` / `MetaContext` / `PaginatedEnvelope<T>`) per ch01 §1 + ch13 §5
+- URL grammar v2.5.68 helpers: `validateBaseUrl` (rejects path/scheme/query/fragment per ch13 §7.2 → `K9O_INVALID_BASE_URL`), `validateSlug`, `projectPath` (member-plane `/@<slug>/...`), `orgPath`, `platformPath` per ch01 §5.4
+- Data-plane DSL `client.from(collection)` with chainable filter builder (eq / neq / gt / gte / lt / lte / in / notIn / like / ilike / is / filter), pagination (limit / cursor), counting (count: none / exact / estimated), and terminal verbs (select / insert / update / delete) per ch04 §3 + §6.4; `update` + `delete` require `.eq('id', '...')` filter (row-mass updates deferred)
+- Project lifecycle (`client.projects.list / create / get / update`) per ch02
+
+52 unit tests pass / 0 fail across 4 test files; tsc clean strict.
+
+Forward sub-cycles add: `client.migrations`, `client.functions`, `client.policies`, `client.audit`, `client.orgs`, `client.gate` (composition), `client.kibo` (composition), `client.extensions` (composition), retry/backoff per ch13 §7.1, subscription/streaming per ch04 §8.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+Kilimanjaro SDK
+Copyright 2026 Formelo Inc.
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @k9o/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Kilimanjaro platform SDK for TypeScript / JavaScript.
+
+`createClient` + data-plane DSL + project lifecycle + cross-cutting `KError` + meta accessor sugar. Composes with `@k9o/gate` (auth pillar) and `@k9o/extensions` (extension consumption pillar).
+
+## Status
+
+v0.1.0 — first-pass scaffold. Surfaces shipped:
+
+- `createClient(options)` — factory + baseUrl validation per ch13 §7
+- `client.from(collection)` — data-plane DSL: `.select()` / `.insert()` / `.update()` / `.delete()` with filter chain (eq / neq / gt / gte / lt / lte / in / notIn / like / ilike / is / filter) + pagination (limit / cursor / count) per ch04 §3 + §6.4
+- `client.projects` — list / create / get / update per ch02
+- `KError` — closed-taxonomy error class + `kerrorFromWire` rehydration per ch01 §2
+- URL grammar v2.5.68 — `validateBaseUrl` / `validateSlug` / `projectPath` / `orgPath` / `platformPath` per ch01 §5.4
+
+Forward sub-cycles add: `client.migrations`, `client.functions`, `client.policies`, `client.audit`, `client.orgs`, `client.gate` (composition with `@k9o/gate`), `client.kibo` (composition with future `@k9o/kibo`), `client.extensions` (composition with `@k9o/extensions`), retry/backoff, subscription/streaming.
+
+## Install
+
+```bash
+bun add @k9o/core
+```
+
+## Quick start
+
+```typescript
+import { createClient, KError } from "@k9o/core";
+
+const client = createClient({
+  baseUrl: "https://acme.api.k9o.io",
+  apiKey: process.env.K9O_API_KEY,
+  orgSlug: "acme",
+  projectSlug: "member-portal",
+});
+
+try {
+  const { data, meta } = await client.from("posts").select().limit(10);
+  console.log(data);
+  console.log("next cursor:", (meta as { cursor?: { next: string | null } }).cursor?.next);
+} catch (e) {
+  if (e instanceof KError && e.code === "K9O_TIER_CAP_HIT") {
+    console.warn(e.message, e.recommendation);
+  } else {
+    throw e;
+  }
+}
+```
+
+## Architecture
+
+`@k9o/core` is the umbrella TypeScript factory that:
+
+- Constructs the `K9oClient` with cross-cutting HTTP, KError, and URL grammar
+- Hosts pillars that don't have their own dedicated package (data-plane, projects, migrations, functions, policies, audit, orgs)
+- Composes pillar packages (`@k9o/gate`, `@k9o/extensions`, future `@k9o/kibo`) under namespaces on the client
+
+Customers may import pillar packages directly when they only need one slice — `@k9o/gate` standalone for Auth0-parity deployments, `@k9o/extensions` standalone for extension-only consumption — or import `@k9o/core` for the full platform surface.
+
+## License
+
+Apache-2.0 © Formelo Inc. See `LICENSE` and `NOTICE`.

package/dist/chunk-2VSTF5UU.js

@@ -0,0 +1,33 @@
+// src/kerror.ts
+var KError = class extends Error {
+  code;
+  context;
+  recommendation;
+  status;
+  requestId;
+  constructor(init) {
+    super(init.message);
+    this.name = "KError";
+    this.code = init.code;
+    this.context = Object.freeze({ ...init.context ?? {} });
+    this.recommendation = init.recommendation ?? null;
+    this.status = init.status ?? null;
+    this.requestId = init.requestId ?? null;
+  }
+};
+function kerrorFromWire(wire, status) {
+  return new KError({
+    code: wire.code,
+    message: wire.message,
+    context: wire.context ?? {},
+    recommendation: wire.recommendation ?? null,
+    status,
+    requestId: wire.requestId ?? null
+  });
+}
+
+export {
+  KError,
+  kerrorFromWire
+};
+//# sourceMappingURL=chunk-2VSTF5UU.js.map

package/dist/chunk-2VSTF5UU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kerror.ts"],"sourcesContent":["/**\n * `KError` — the closed-taxonomy error class returned by every `@k9o/core`\n * surface on non-2xx gateway responses or SDK-side validation failures.\n *\n * TypeScript / JavaScript throw on error; the per-language SDKs deliver this same payload\n * via their idiomatic mechanism (Go tuple-return; Rust Result; Python\n * raise; etc.) without changing the field shape.\n *\n * Fields:\n *   - `code`     — closed-taxonomy string (e.g. `K9O_TIER_CAP_HIT`,\n *                  `K9O_PROJECT_NOT_FOUND`); unknown codes pass through\n *                  with `code` preserved + `INTERNAL_ERROR` family\n *                  classification recorded in `context.originalCode`.\n *   - `message`  — human-readable explanation.\n *   - `context`  — structured per-code payload (immutable; frozen).\n *   - `recommendation` — actionable next step (may be null when the\n *                  gateway didn't return one).\n *   - `status`   — HTTP status the gateway returned (or null for\n *                  SDK-side construct-time errors like\n *                  `K9O_INVALID_BASE_URL` per ch13 §7.2).\n *   - `requestId` — gateway-emitted trace ID for downstream correlation.\n *\n * Standalone `@k9o/gate` ships its own `GateError` for the Auth0-parity\n * deployment shape; when `@k9o/gate` is composed inside `@k9o/core`,\n * `GateError` semantics align with `KError extends KError` (alignment still open).\n * Until then `KError` is the canonical error type returned by `@k9o/core` surfaces; `GateError` thrown by\n * `@k9o/gate`-delegated surfaces remain `KError`-shape-compatible\n * (both expose the same `code` / `message` / `context` / `recommendation`\n * fields) so caller code that narrows on `code` works against either.\n */\n\n/**\n * Wire-shape sentinel matching the gateway's `KError` JSON payload. The HTTP client recognises this on non-2xx responses\n * and rehydrates it into a `KError` instance.\n */\nexport type KErrorWire = {\n  code: string;\n  message: string;\n  context?: Record<string, unknown>;\n  recommendation?: string | null;\n  requestId?: string;\n};\n\n/**\n * The customer-facing error type. Every `@k9o/core` surface throws this\n * on non-2xx upstream responses, transport failures, or SDK-side\n * validation failures.\n */\nexport class KError extends Error {\n  readonly code: string;\n  readonly context: Readonly<Record<string, unknown>>;\n  readonly recommendation: string | null;\n  readonly status: number | null;\n  readonly requestId: string | null;\n\n  constructor(init: {\n    code: string;\n    message: string;\n    context?: Record<string, unknown>;\n    recommendation?: string | null;\n    status?: number | null;\n    requestId?: string | null;\n  }) {\n    super(init.message);\n    this.name = \"KError\";\n    this.code = init.code;\n    this.context = Object.freeze({ ...(init.context ?? {}) });\n    this.recommendation = init.recommendation ?? null;\n    this.status = init.status ?? null;\n    this.requestId = init.requestId ?? null;\n  }\n}\n\n/**\n * Rehydrate a wire `KError` payload into a typed `KError` instance.\n * Unlike `@k9o/gate.gateErrorFromWire`, `@k9o/core` does not maintain\n * a hand-curated allow-list of known codes — the gateway's KError\n * code-space is open-ended and curated centrally per ch11; the SDK\n * preserves whatever code the gateway sends. Code-narrowing in caller\n * code uses string-literal comparison against the well-known codes\n * (e.g. `if (e.code === 'K9O_TIER_CAP_HIT')`).\n */\nexport function kerrorFromWire(wire: KErrorWire, status: number): KError {\n  return new KError({\n    code: wire.code,\n    message: wire.message,\n    context: wire.context ?? {},\n    recommendation: wire.recommendation ?? null,\n    status,\n    requestId: wire.requestId ?? null,\n  });\n}\n"],"mappings":";AAgDO,IAAM,SAAN,cAAqB,MAAM;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAOT;AACD,UAAM,KAAK,OAAO;AAClB,SAAK,OAAO;AACZ,SAAK,OAAO,KAAK;AACjB,SAAK,UAAU,OAAO,OAAO,EAAE,GAAI,KAAK,WAAW,CAAC,EAAG,CAAC;AACxD,SAAK,iBAAiB,KAAK,kBAAkB;AAC7C,SAAK,SAAS,KAAK,UAAU;AAC7B,SAAK,YAAY,KAAK,aAAa;AAAA,EACrC;AACF;AAWO,SAAS,eAAe,MAAkB,QAAwB;AACvE,SAAO,IAAI,OAAO;AAAA,IAChB,MAAM,KAAK;AAAA,IACX,SAAS,KAAK;AAAA,IACd,SAAS,KAAK,WAAW,CAAC;AAAA,IAC1B,gBAAgB,KAAK,kBAAkB;AAAA,IACvC;AAAA,IACA,WAAW,KAAK,aAAa;AAAA,EAC/B,CAAC;AACH;","names":[]}

package/dist/chunk-FVWKL5UQ.js

@@ -0,0 +1,234 @@
+import {
+  KError,
+  kerrorFromWire
+} from "./chunk-2VSTF5UU.js";
+
+// src/retry.ts
+var RETRYABLE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS", "DELETE"]);
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([502, 503, 504]);
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  backoff: "exponential",
+  initialDelayMs: 100,
+  maxDelayMs: 5e3
+};
+function isRetryable(error, method) {
+  if (!RETRYABLE_METHODS.has(method.toUpperCase())) return false;
+  if (!(error instanceof KError)) return false;
+  if (error.code === "K9O_UPSTREAM_UNAVAILABLE") return true;
+  if (error.status !== null && RETRYABLE_STATUS.has(error.status)) return true;
+  if (error.status === 429) return true;
+  return false;
+}
+function computeDelay(config, attempt) {
+  let base;
+  if (config.backoff === "none") return 0;
+  if (config.backoff === "linear") base = config.initialDelayMs * (attempt + 1);
+  else base = config.initialDelayMs * Math.pow(2, attempt);
+  const capped = Math.min(base, config.maxDelayMs);
+  const jitter = capped * 0.25 * (Math.random() * 2 - 1);
+  return Math.max(0, Math.floor(capped + jitter));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withRetry(fn, method, config, sleepImpl = sleep) {
+  const c = {
+    ...DEFAULT_RETRY_CONFIG,
+    ...config ?? {}
+  };
+  let lastError;
+  for (let attempt = 0; attempt <= c.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (e) {
+      lastError = e;
+      if (attempt === c.maxRetries) break;
+      if (!isRetryable(e, method)) break;
+      const delay = computeDelay(c, attempt);
+      if (delay > 0) await sleepImpl(delay);
+    }
+  }
+  throw lastError;
+}
+
+// src/region.ts
+import { resolveRegionalOrigin, regionalOriginFromLocation } from "@k9o/gate";
+
+// src/http.ts
+async function request(config, init) {
+  return withRetry(() => requestOnce(config, init), init.method, config.retryConfig);
+}
+async function requestOnce(config, init) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new KError({
+      code: "K9O_INTERNAL_ERROR",
+      message: "No fetch implementation available \u2014 pass {fetch} in createClient options for runtimes without a global fetch",
+      context: {},
+      recommendation: "Use Node 18+, Bun 1.1+, or a modern browser; otherwise supply a fetch polyfill via the fetch option."
+    });
+  }
+  const url = buildUrl(await resolveRegionalOrigin(config), init.path, init.query);
+  const headers = {
+    accept: "application/json",
+    ...config.defaultHeaders ?? {},
+    ...config.projectSlug ? { "x-k9o-project-slug": config.projectSlug } : {},
+    ...config.orgSlug ? { "x-k9o-org-slug": config.orgSlug } : {},
+    ...init.headers ?? {}
+  };
+  const bearer = init.bearerToken ?? config.apiKey;
+  if (typeof bearer === "string" && bearer.length > 0) {
+    headers["authorization"] = `Bearer ${bearer}`;
+  }
+  const requestInit = {
+    method: init.method,
+    headers
+  };
+  if (init.body !== void 0) {
+    if (typeof FormData !== "undefined" && init.body instanceof FormData) {
+      requestInit["body"] = init.body;
+    } else {
+      headers["content-type"] = "application/json";
+      requestInit["body"] = JSON.stringify(init.body);
+    }
+  }
+  let response;
+  try {
+    response = await fetchImpl(url, requestInit);
+  } catch (e) {
+    throw new KError({
+      code: "K9O_UPSTREAM_UNAVAILABLE",
+      message: `Network error reaching ${url}: ${e instanceof Error ? e.message : String(e)}`,
+      context: { url },
+      recommendation: "Check connectivity to the gateway; retry with backoff if transient."
+    });
+  }
+  if (response.status === 204) {
+    return { data: void 0, meta: {} };
+  }
+  let parsed;
+  try {
+    parsed = await response.json();
+  } catch (e) {
+    throw new KError({
+      code: "K9O_INTERNAL_ERROR",
+      message: `Failed to parse JSON response from ${url}: ${e instanceof Error ? e.message : String(e)}`,
+      context: { url, status: response.status },
+      status: response.status
+    });
+  }
+  if (response.status >= 200 && response.status < 300) {
+    if (!isEnvelope(parsed)) {
+      throw new KError({
+        code: "K9O_INTERNAL_ERROR",
+        message: `Malformed envelope from ${url}: expected {data, meta}`,
+        context: { url, status: response.status },
+        status: response.status
+      });
+    }
+    return parsed;
+  }
+  if (isKErrorWire(parsed)) {
+    throw kerrorFromWire(parsed, response.status);
+  }
+  throw new KError({
+    code: "K9O_INTERNAL_ERROR",
+    message: `Upstream returned ${response.status} with non-KError body`,
+    context: { url, status: response.status, body: parsed },
+    status: response.status
+  });
+}
+async function requestStream(config, init) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new KError({
+      code: "K9O_INTERNAL_ERROR",
+      message: "No fetch implementation available \u2014 pass {fetch} in createClient options",
+      context: {},
+      recommendation: "Use Node 18+, Bun 1.1+, or a modern browser; otherwise supply a fetch polyfill via the fetch option."
+    });
+  }
+  const url = buildUrl(await resolveRegionalOrigin(config), init.path, init.query);
+  const headers = {
+    accept: init.accept ?? "text/event-stream",
+    ...config.defaultHeaders ?? {},
+    ...config.projectSlug ? { "x-k9o-project-slug": config.projectSlug } : {},
+    ...config.orgSlug ? { "x-k9o-org-slug": config.orgSlug } : {},
+    ...init.headers ?? {}
+  };
+  const bearer = init.bearerToken ?? config.apiKey;
+  if (typeof bearer === "string" && bearer.length > 0) {
+    headers["authorization"] = `Bearer ${bearer}`;
+  }
+  const requestInit = { method: init.method, headers };
+  if (init.body !== void 0) {
+    headers["content-type"] = "application/json";
+    requestInit["body"] = JSON.stringify(init.body);
+  }
+  let response;
+  try {
+    response = await fetchImpl(url, requestInit);
+  } catch (e) {
+    throw new KError({
+      code: "K9O_UPSTREAM_UNAVAILABLE",
+      message: `Network error reaching ${url}: ${e instanceof Error ? e.message : String(e)}`,
+      context: { url },
+      recommendation: "Check connectivity to the gateway; retry with backoff if transient."
+    });
+  }
+  if (response.status < 200 || response.status >= 300) {
+    let parsed = null;
+    try {
+      parsed = await response.json();
+    } catch {
+    }
+    if (isKErrorWire(parsed)) throw kerrorFromWire(parsed, response.status);
+    throw new KError({
+      code: "K9O_INTERNAL_ERROR",
+      message: `Upstream returned ${response.status} opening stream`,
+      context: { url, status: response.status, body: parsed },
+      status: response.status
+    });
+  }
+  if (response.body === null) {
+    throw new KError({
+      code: "K9O_INTERNAL_ERROR",
+      message: `Stream response from ${url} has no body`,
+      context: { url, status: response.status },
+      status: response.status
+    });
+  }
+  return response;
+}
+function buildUrl(baseUrl, path, query) {
+  const trimmedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const trimmedPath = path.startsWith("/") ? path : `/${path}`;
+  let url = `${trimmedBase}${trimmedPath}`;
+  if (query !== void 0) {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0) params.set(k, String(v));
+    }
+    const qs = params.toString();
+    if (qs.length > 0) url += `?${qs}`;
+  }
+  return url;
+}
+function isEnvelope(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return "data" in v && "meta" in v && typeof v.meta === "object" && v.meta !== null;
+}
+function isKErrorWire(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.code === "string" && typeof v.message === "string";
+}
+
+export {
+  request,
+  requestOnce,
+  requestStream
+};
+//# sourceMappingURL=chunk-FVWKL5UQ.js.map