@cavi-ai/api-client 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,12 @@
+# Architecture
+
+The durable architecture guidance now lives in [README.md](README.md):
+
+- Layered ownership and dependency direction: see "Layered architecture".
+- Provider plugin boundaries: see "Adding a gateway provider".
+- Transport, media, wiki, React, adapter, team-manifest, and path contracts:
+  see the matching sections under "Reference".
+- Enforced package boundaries: see "Development" and
+  `src/__tests__/package-hardening.test.ts`.
+
+This file is kept only as a stable pointer for direct links.

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to `@cavi-ai/api-client` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- GitHub Actions CI for PRs and pushes to `main`, running install, tests, build,
+  and package dry-run across Node 20 and 22.
+- GitHub Actions publish workflow for GitHub releases and manual dry-runs,
+  publishing to npm with provenance via OIDC trusted publishing (no token).
+- Husky `pre-commit` and `pre-push` hooks for local test/build/package gates.
+
+## [0.1.0] - 2026-05-25
+
+Initial public pre-1.0 release.
+
+`@cavi-ai/api-client` is the gateway-agnostic TypeScript client for agent
+runtimes: HTTP + WebSocket access to runs, capabilities, media, wikis, team
+registries, and fleet snapshots, with structured graceful degradation built in.
+
+### Added
+
+- **Gateway-agnostic core.** `BaseHttpApiClient` (fetch wrapper: timeout, bearer
+  auth, trace hooks, typed `HttpApiError`) and `GatewayRpcClient` (WebSocket RPC:
+  device-auth handshake, backpressure, reconnect, redacted trace) as the only two
+  network-touching primitives.
+- **Provider model.** `createGatewayApiClient(opts, { provider | env })` selecting
+  `gateway` / `hermes` / `openclaw` implementations behind one interface, with
+  `Hermes*` / `OpenClaw*` names available from provider-specific exports.
+- **Provider plugin boundary.** `createGatewayProviderRegistry` and
+  `GatewayProviderModule` (exported from `@cavi-ai/api-client/core/gateway`) so
+  third-party gateways register at the factory boundary without forking the package.
+- **Gateway resources.** Media (`GatewayMediaApiClient`), wiki
+  (`GatewayWikiApiClient`), and agent-config (`GatewayAgentConfigApiClient`)
+  clients with provider adapters.
+- **Run streaming.** `GatewaySseRunEventProvider`, run-event stream composition,
+  and `streamGatewayChatRun` over canonical run/run-stream contracts in `core`.
+- **Capabilities UI helpers.** `extractGatewayCommandCatalog`,
+  `buildAgentSlashShortcuts`, `buildAgentMentionChips`, `buildAgentCommandSurface`
+  sourced from `/v1/capabilities`.
+- **Graceful degradation contract.** `withFallback` / `withMutationResult` return
+  a typed `DataEnvelope` with `source: "mock"` and a structured `contractGap` on
+  transport/backend failure; 401/403 and `unknown`-classified errors still throw.
+- **Overrideable fallback providers.** Core snapshots and operator-control
+  adapters default to neutral empty fallbacks; CAVI-specific snapshot/control data
+  is opt-in through `createCaviSnapshotFallbackProvider` and
+  `createCaviControlAdapterFallbackProvider`.
+- **Runtime override hooks.** RPC preauth env keys, request timeout, max
+  concurrency, default scopes, provider fallbacks, and core default values can be
+  overridden by the host app or provider module.
+- **Path contracts.** Route literals owned by `*paths.ts` files
+  (`src/contracts/paths.ts`, `src/extensions/cavi/contracts/paths.ts`) and
+  surface owner files, with `resolvePath(key, mode)` for `GatewayMode` resolution.
+- **Team manifest.** Runtime-supplied team / member / workspace / action routing
+  via `normalizeTeamManifest`, generated route grammar, workspace-path
+  whitelisting, action override resolution, duplicate detection, and hardened
+  dynamic path validation. `TEAM_REGISTRY_CONFIG` ships empty.
+- **CAVI manifest example.** A plugin-owned CAVI team manifest example and fixture
+  demonstrate how consumers supply teams, portal bindings, workspaces, and action
+  routes without baking registry data into the package.
+- **React bindings.** `GatewayClientProvider` and `useGatewayClient` /
+  `useGatewayRpc` / `useGatewayEvents` / `useGatewayConnectionState` /
+  `useGatewayEventStream` hooks (React is an optional peer dependency).
+- **UI data adapters.** `createCaviControlAdapters` combining gateway WebSocket
+  RPC with HTTP and fallback providers.
+- **Environment + repo-root resolution.** `resolveHttpApiConfigFromEnv`,
+  `requireRepoRoot` / `resolveRepoRoot`.
+- **Subpath exports** for `core/*`, `contracts`, `extensions/cavi`,
+  `providers/hermes`, `providers/openclaw`, and `react`.
+- **Tooling.** MIT license, `vitest run --coverage` via `@vitest/coverage-v8`,
+  `prepack` / `prepublishOnly` gates, package docs in the npm tarball, and
+  package-boundary hardening tests in `src/__tests__/package-hardening.test.ts`.
+
+[Unreleased]: https://github.com/sasan1200/cavi-api-client/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sasan1200/cavi-api-client/releases/tag/v0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,158 @@
+# Contributing to @cavi-ai/api-client
+
+Thanks for contributing. This package is the shared bridge between many agent
+runtimes and the apps that consume them, so the bar is: **adding a provider or a
+feature should be additive — a small module, not a fork.** This guide explains the
+workflow, the boundary rules, and the checklists for the two most common
+contributions (a new gateway provider, a new feature).
+
+## Quick start
+
+```sh
+git clone https://github.com/sasan1200/cavi-api-client.git
+cd cavi-api-client
+pnpm install
+
+pnpm test           # vitest run — guardrails + behavior (the only test command)
+pnpm run coverage   # coverage report (text + html + lcov)
+pnpm run build      # tsc → dist/
+pnpm run lint:md    # markdownlint on published + contributor docs
+pnpm run verify     # tests + build + lint:md + pack dry-run
+pnpm exec tsc --noEmit # typecheck only
+```
+
+- **Node `>=20`.** Target ES2022, `strict` on.
+- **pnpm `10.32.1`.** Corepack reads `packageManager` and installs from
+  `pnpm-lock.yaml`.
+- **There is no separate linter.** `tsc` under `strict` is the type gate.
+- **ESM throughout.** Relative imports use the `.js` extension on `.ts` sources
+  (`moduleResolution: "Bundler"`). Import `from "./foo.js"`, not `"./foo"`.
+- **Husky hooks.** `pre-commit` runs `pnpm test`; `pre-push` runs
+  `pnpm run verify`.
+
+## The package boundary (read this first)
+
+The boundary is enforced by tests, not honor system. Before you start, skim
+[`src/__tests__/package-hardening.test.ts`](src/__tests__/package-hardening.test.ts) — it is the
+authoritative contract. It fails the build on:
+
+- Imports of forbidden host packages (`@cavi/data`, `@cavi/domain`,
+  `@cavi/gateway-client`, `@cavi/gateway-transforms`, `@mobile-cavi/*`).
+- API route literals (bare or URL-embedded) outside `*paths.ts` and
+  `contracts/surfaces.ts`.
+- Layout drift (reappearance of the pre-restructure flat layout, non-allowlisted
+  files at `src/` root, `tsconfig.json` `include` drifting from its allowlist).
+- Product team-registry slugs baked into the package (registry data is
+  runtime-supplied; `TEAM_REGISTRY_CONFIG.teams` ships empty).
+
+**Update a hardening test only when the boundary intentionally changes**, and say
+so explicitly in your PR.
+
+### Dependency direction
+
+```text
+core → contracts
+core/contracts → extensions/cavi
+core/contracts → providers/hermes | providers/openclaw | react
+```
+
+Lower layers never import upward. Concretely:
+
+- **`core/`** is gateway-agnostic. No product knowledge, no `extensions/cavi/`,
+  concrete `providers/`, or `react/` imports. Universal concepts (runs, run-stream events, transports) live
+  here.
+- **`contracts/`** owns global paths, surfaces, and the agnostic team manifest. No imports
+  from `extensions/` or providers.
+- **`extensions/cavi/`** owns CAVI-specific clients, extension contracts, adapters,
+  domain DTOs, registry wrappers.
+- **`core/gateway/providers/`** is the plugin boundary; `providers/hermes` and
+  `providers/openclaw` are the built-in adapters.
+- **`react/`** imports `core/gateway` and React only.
+
+See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the full module map.
+
+Gateway internals are grouped by owner folder under `src/core/gateway/`
+(`client`, `agent`, `run`, `rpc`, `snapshots`, `resources`, `envelope`,
+`portal`). `src/core/gateway/index.ts` is the only aggregate in that folder and
+must re-export owner-folder indexes directly. New source should import from the
+owner folder or from the canonical aggregate.
+
+## Adding a gateway provider
+
+The whole point of the provider model is that you do **not** edit core to add a
+gateway. A provider is a `GatewayProviderModule`. Built-in wiring (Hermes,
+OpenClaw) lives in `src/providers/hermes/provider-module.ts` and
+`src/providers/openclaw/provider-module.ts`; third-party providers are passed as
+modules/registries by the host app.
+
+Checklist:
+
+1. **Implement the module.** At minimum `kind`, optional `aliases`, and the
+   relevant `create*` factory. Reuse `GatewayApiClient` with a surface name; only
+   override what genuinely differs (headers, endpoint map, default surface).
+
+   ```ts
+   import { GatewayApiClient } from "@cavi-ai/api-client";
+   import { type GatewayProviderModule } from "@cavi-ai/api-client/core/gateway";
+
+   export const acmeProvider: GatewayProviderModule = {
+     kind: "acme",
+     aliases: ["acme-gateway"],
+     createApiClient: (options) => new GatewayApiClient(options, "acme-api"),
+   };
+   ```
+
+2. **Do not fork the engine.** The SSE parser, RPC protocol, retry semantics, and
+   trace behavior are written once in `core`. A provider customizes headers,
+   endpoint maps, factories, or defaults — nothing else.
+3. **Routes go in path-owner files.** If your provider needs new routes, add them
+   to `src/contracts/paths.ts` (or a surface contract), never inline.
+4. **Keep keys clean.** Keys are normalized (trimmed, lowercased); `generic`
+   aliases `gateway`. Don't shadow built-in keys — duplicates throw by design.
+5. **Test it.** Construct the client with a mocked `fetch`/`WebSocket` and assert
+   the first request hits the right path with the right headers. Add a registry
+   test if you add resolution behavior.
+
+## Adding a feature
+
+1. **Decide the layer.** Generic transport/data/runtime → `core/`. A route or
+   global surface contract → `contracts/`. CAVI-specific shaping or routes →
+   `extensions/cavi/`. Provider-only behavior → `providers/<name>/`.
+2. **Don't duplicate a core type.** If `core` already models the concept (a run, a
+   run-stream event), re-export and extend — never copy it downstream.
+3. **Route every loader through degradation.** New data loaders use `withFallback`
+   / `withMutationResult` with a mock and an expected-contract summary. Remember:
+   401/403 and `unknown`-classified errors must still throw.
+4. **Export from the right entry.** Add public API to `src/index.ts` and, if it
+   belongs to a slice, the relevant subpath entry. Keep provider-specific names out
+   of the gateway-agnostic surface unless the provider module owns that name.
+
+## Tests
+
+- `pnpm test` runs the full suite (guardrails + behavior). It must pass before a PR
+  merges.
+- Test files are `*.test.ts(x)` under `src/__tests__/**`; they are excluded from
+  the build. Production modules must not import test fixtures.
+- For new public exports, add a smoke test that constructs the client/helper and
+  verifies its contract (path + headers, or transform output).
+- Run `pnpm run coverage` and try not to regress coverage on the surface you touch.
+
+## Commits and pull requests
+
+- Keep PRs focused. One provider, one feature, or one fix per PR.
+- Describe **what** changed and **why**; if you touched a hardening test, explain
+  the boundary change.
+- Update [`CHANGELOG.md`](CHANGELOG.md) under `[Unreleased]` for any user-facing
+  change.
+- Make sure `pnpm test` and `pnpm run build` pass locally.
+
+## Reporting issues
+
+- Bugs and feature requests: <https://github.com/sasan1200/cavi-api-client/issues>.
+- Security vulnerabilities: **do not** open a public issue — see
+  [`SECURITY.md`](SECURITY.md).
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+[MIT License](LICENSE).

package/LICENSE

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