@collective-intelligence/external-apps-client-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# `@collective-intelligence/external-apps-client-sdk`
 
-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.
+Browser-safe, React-free APIs for Collective Intelligence external applications.
+The root entrypoint provides federated login, typed CI operations, and direct or
+same-origin proxy transports. It contains no confidential credentials or
+framework state.
+
+`createFederatedAuth` implements the public OAuth authorization-code flow with
+PKCE. It validates same-origin return targets, keeps the login transaction in
+session storage, exchanges the callback code, tracks token expiry, and supports
+logout and reauthorization. A server runtime remains responsible for any
+confidential proxy credentials and durable application sessions.
+
+`createClient` binds a typed transport to CI operations for agents, attachments,
+context, Knowledge, runs, skills, and workflows. Call `forOrganization` to bind
+those operations to one organization.
+
+For `workflows_invoke`, pass exactly one target: `workflowId` for a workflow
+UUID or `workflowFqn` for its stable fully qualified name. Both forms use the
+same organization-scoped run route and remain subject to the application's
+workflow binding.
+
+Skill and workflow runs return a `runId` without waiting for the run to
+finish. `client.forOrganization(id).runs.follow({ runId })` (or the standalone
+`followRun`) polls the run snapshot and its event pages until a terminal event
+or status, then resolves with the last event page it read. It reads the
+snapshot before each page, so once the snapshot is terminal that page holds the
+run's last events. It waits up to
+`DEFAULT_FOLLOW_RUN_DEADLINE_MS` (10 minutes: the 5-minute server AI deadline
+plus slack) before throwing `Run did not finish`; pass `deadlineMs` to change
+it and `signal` to cancel. Polling starts every `idleMs` (50 ms) and backs off
+to at most one second while no new events arrive.
+
+The `@collective-intelligence/external-apps-client-sdk/resources` entrypoint
+provides the portable resource contracts and `createResourceClient`. A resource
+client supports filtering, sorting, text search, page or cursor pagination,
+opaque IDs and revisions, optimistic concurrency, idempotency, soft deletion,
+restore, and hard deletion according to the resource's declared capabilities.
+
+## Common entity CRUD
+
+Use the explicit `protocol: "entity"` option for the common page-based CRUD API.
+Both the root and `/resources` entrypoints export these builders:
+
+```ts
+import {
+  createEntityHttpTransport,
+  createResourceClient
+} from "@collective-intelligence/external-apps-client-sdk"
+
+const leads = createResourceClient({
+  definition: leadContract,
+  protocol: "entity",
+  transport: createEntityHttpTransport({
+    authentication: { auth, mode: "federated" },
+    destination: {
+      endpoint: "https://customer.example/api/resources/leads",
+      kind: "gateway"
+    }
+  })
+})
+
+const action = {
+  expectedRevision: record.revision,
+  id: record.id,
+  idempotencyKey: crypto.randomUUID(),
+  value: { status: "qualified" }
+}
+const result = await leads.update(action)
+```
+
+`leadContract` supplies portable entity/create/update JSON schemas and capabilities.
+`auth` is the configured federated authentication instance. A customer gateway
+using its own CI-derived browser session can use
+`authentication: { mode: "server_delegated" }` instead.
+For direct CI, configure `destination: { kind: "ci", tenantUrl, schemaFqn,
+organizationId }`; the schema FQN selects the CI resource route. These identifiers
+select the route and organization header; the server still authenticates and
+authorizes access. They are configuration, never mutation-body authority.
+
+`createDelegatedApplicationRuntime` owns the sealed-cookie session machine,
+including identity, login, logout, and `runs_follow`. `createFixedWorkflowClient`
+posts a Fixed workflow BFF route and returns `{ runId }`.
+
+The common client exposes `list`, `get`, `create`, `update`, and `delete`.
+`delete` calls the explicit soft-delete route. Every mutation requires an operation
+key; update/delete also require the revision originally edited. Reads accept an
+optional `{ signal }`. Mutations are independent of view unmount cancellation.
+Transport calls send once and do not retry. Retain `action` unchanged for an
+explicit same-action resubmission; a different edit requires a new key.
+
+Failures preserve safe server errors and correlation IDs. `error.outcome` is
+`not_dispatched` for local input/authentication/cancellation failures, `rejected`
+for an explicit backend rejection, or `uncertain` when a dispatched write has no
+valid response. Uncertainty does not prove rollback. Known response fields are
+validated without coercion; compatible extra entity fields are accepted, while
+an incompatible record fails the whole result, including a page.
+
+During migration, omitting `protocol` retains the distinct legacy resource facade,
+including its optional update keys, cursor pagination and explicit lifecycle
+methods. Existing hard-delete behavior is never relabeled as common `delete`.
+
+## Workspace development
+
+The repository's [Effect demo](../../../demo/external-app-effect/README.md)
+documents local Gateway, proxied CI, and direct CI entity bindings. Its shared
+contract package emits the browser-safe contract consumed by both demo apps.
+
+Each package export declares an opt-in `ci-source` condition for workspace
+development. Local TypeScript, Bun, or bundler consumers can enable that
+condition to resolve the matching `src` facade without rebuilding this package.
+Consumers that do not explicitly enable `ci-source`, including packed and
+published npm consumers, continue to resolve the generated `dist` JavaScript
+and declarations.
+
+## Enum value compatibility
+
+Repository-owned enum values use lower `snake_case`. Update gateway manifests,
+request payloads and saved resource filters together with their consumers. For
+example, resource filters use `starts_with` and `is_null`, lifecycle operation
+values use `soft_delete` and `hard_delete`, and gateway principal kinds use
+`detached_user` and `service_principal`. Public method and capability property
+names such as `softDelete` remain unchanged. External HTTP, OAuth, JSON Schema
+and provider values retain their required spelling at their adapter boundaries.