@ai-matrx/api 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog — @ai-matrx/api
+
+## 0.1.1
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/api/v0.1.0..npm/api/v0.1.1 -- apps/shared/api`).
+No source changes intended and no consumer action required.
+
+## 0.1.0 addendum — 2026-10-09 (before the first npm release)
+
+The credentials port MOVED to `@ai-matrx/auth/credentials`; `@ai-matrx/api/credentials` and the
+root re-export it unchanged. The build inlines it (code and types) until `@ai-matrx/auth` is on npm.
+
+### Consumer action
+
+None.
+
+## 0.1.0 — 2026-10-08
+
+First release (package lines v3 steps 3–4).
+
+- Root: `createApi` — base URL per deployment from the contract's deployment map, `X-Request-Id` on every call, connect/total timeouts, retry of idempotent reads, one error model (`MatrxApiError`, `NetError`, `OrganizationContextError`).
+- ONE credentials setting, five kinds named after the contract's auth tiers: `user`, `guest`, `api_key`, `service`, `scoped` (`MATRX_HEADERS` names every shared header).
+- Organization binding per operation's `x-matrx-org`: `required` fails closed before the wire, `optional` sends when bound, `exempt` never sends.
+- Moved in (behavior verbatim): the Matrx transport, call pipeline, protocol fallback, org context, server error model, warm-up, run-wait, operations/rejoin/follow-server-job, provider failures (from `@ai-matrx/agents/matrx`); credentials and the net resilience trio (from `@ai-matrx/data`).
+- Generated from aidream `api-contract/`: one section per domain (`@ai-matrx/api/<domain>`, 28), each operation a standalone typed function; `/schemas` (schemas reached from more than one domain); a per-domain path-keyed `call`; `/stream` (NDJSON, SSE, conditional `*_or_json`); mandate keys in `/intelligence`. `node scripts/generate.mjs --check` fails on drift; the generator is red on an unmapped route.
+
+### Consumer action
+
+None. `@ai-matrx/agents/matrx`, `@ai-matrx/agents/stream/*` and `@ai-matrx/data`'s credentials and `/net` keep their paths (they re-export from here from their next release).
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+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

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @ai-matrx/api
 
-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.
+The one way every app talks to every AI Matrx server. Generated from the server contract and split by area, so an app only loads the requests it calls. It never holds screens, app state or database code.
+
+```ts
+import { createApi } from "@ai-matrx/api";
+import { listAssets } from "@ai-matrx/api/files";
+
+const api = createApi({ credentials: { kind: "api_key", apiKey: process.env.MATRX_API_KEY! }, organizationId });
+const page = await listAssets(api, { query: { limit: 50 } });
+```
+
+- **Credentials** — one setting: a credential, a getter, or a `CredentialsPort` (`user`, `guest`, `api_key`, `service`, `scoped`).
+- **Organization** — bound once; sent per each operation's contract rule (required / optional / exempt).
+- **Routing** — each operation knows which deployment answers; override with `baseUrls` or `resolveBaseUrl`.
+- **Streams** — NDJSON/SSE operations return an async iterable; `*_or_json` operations return `{ kind: "json" } | { kind: "stream" }`.
+- **Sections** — `@ai-matrx/api/<domain>` per domain, `/schemas`, `/stream`, `/net`, `/credentials`. Importing one domain loads no other domain's code.
+
+Regenerate after a server contract change: `node scripts/generate.mjs` (input: aidream `api-contract/`). `--check` fails on drift.
+
+## Gates
+
+`pnpm check:package` runs the generator `--check`, the build, exports agreement, publint and the section probe (`scripts/section-probe.mjs`: no domain section loads another domain's code; one imported operation bundles exactly one operation descriptor).