@oxchannels/sdk 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# @oxchannels/sdk
+
+> **Closed beta.** OxChannels is in a closed beta. This package is published so invited
+> partners can install it with `npm install`, but it is useful only with an API key issued by
+> the OxChannels team for your workspace, and there is no self-service sign-up yet. Endpoints,
+> contracts and this SDK may still change between beta releases without a major version bump;
+> read the changelog notes on each release before upgrading. To join the beta or report an
+> issue, contact OxChannels at https://oxchannels.com.
+
+Typed TypeScript client for the OxChannels REST API. Everything in it is generated from the sealed
+OpenAPI contracts (`docs/api/generated/openapi-*-contract-v2.json`): `openapi-typescript@7.13.0`
+produces four isolated path sets, `openapi-fetch@0.17.0` supplies the runtime, and there is no
+handwritten wire DTO anywhere. The package directory in the repository is `packages/openapi-client`.
+
+- Guide with the full publishing walkthrough: `QUICKSTART.md`, shipped inside this package
+  (source: `docs/guides/sdk-quickstart.md` in the OxChannels repository).
+- Single-source example, type-checked on every test run: `examples/publish-everywhere.ts` in the
+  repository package directory.
+- Runtime: Node 24 (or any runtime with WHATWG `fetch`); ESM only.
+
+## What you can do with it
+
+- Read the workspace context and the publishing context: which channels are connected, which
+  targets are ready, what each target can carry (text, image, video, variants, limits).
+- Upload media once and reuse it across targets.
+- Create one publication per target against the capability snapshot you were shown, submit it,
+  and follow the operation to a confirmed effect with the provider's URL of the content.
+- Receive webhooks about operation status and reconcile idempotently on retries.
+
+Supported channels in the beta: Bluesky, Facebook pages, Instagram business accounts, LinkedIn,
+Mastodon, Telegram channels, Threads, TikTok, X and YouTube. Every request is authenticated with a
+workspace-scoped API key; the key carries scopes (`context:read`, `targets:read`,
+`operations:read`, `operations:write`, `webhooks:manage`) and can be rotated or revoked in the
+OxChannels panel.
+
+## Install
+
+```bash
+npm install @oxchannels/sdk
+```
+
+The tarball carries `dist/` (runtime and `.d.ts`), the four OpenAPI documents it was generated from
+(`contracts/*.json`), `generated/provenance.json` with the SHA-256 of every source and output,
+`QUICKSTART.md` and the licence. It has one runtime dependency, `openapi-fetch`.
+
+## First publication
+
+The partner surface is what an external system uses to publish. Create one client per service key
+(the key comes from the panel, API keys), then walk the flow: who am I, where can I publish,
+upload media once, create a publication per target, submit the action, follow it.
+
+```ts
+import { createOxStudioClient } from '@oxchannels/sdk';
+
+const client = createOxStudioClient({
+  baseUrl: 'https://api.oxchannels.com',
+  serviceKey: () => process.env.OXS_API_KEY!,
+});
+
+const context = (await client.GET('/v1/integration/publishing-context')).data!;
+for (const target of context.targets) {
+  if (target.readiness !== 'READY' || target.capability === null) continue;
+
+  const publication = (
+    await client.POST('/v1/integration/publications', {
+      body: {
+        targetId: target.targetId,
+        capabilityGeneration: target.capability.generation,
+        capabilityHash: target.capability.snapshotHash,
+        body: 'Hello from @oxchannels/sdk',
+        locale: 'en',
+        mediaAssetIds: [],
+        options: {},
+        clientReference: `my-run:${target.targetId}`,
+      },
+    })
+  ).data!;
+
+  const action = (
+    await client.POST('/v1/integration/publishing-actions', {
+      body: {
+        mode: 'PUBLISH_NOW',
+        contentRevisionId: publication.revision.id,
+        targetIds: [target.targetId],
+        oxStudioRun: {
+          schemaVersion: 'ox-studio-run.v1',
+          workflowRunId: 'my-run',
+          workflowTaskId: 'publish',
+          taskGeneration: 1,
+        },
+      },
+    })
+  ).data!;
+  console.log(target.connectorKey, action.actionId, action.outcome);
+}
+```
+
+`examples/publish-everywhere.ts` is the complete version: media upload with the scan wait,
+per-target stale-snapshot recovery, polling the action to a terminal outcome and the webhook
+subscription. Every non-2xx response is thrown as `OxChannelsApiErrorV2`, so `data` is defined
+whenever a call returns.
+
+## Clients and surfaces
+
+- `createPartnerClient` (alias `createOxStudioClient`) accepts an OxChannels service key as Bearer
+  authentication (`serviceKey`, or the equivalent `bearer` spelling; never both) and an optional
+  correlation ID. Its base URL must use HTTPS. Development HTTP is available only through
+  `allowInsecureLoopbackForDevelopment: true` and only for the exact loopback hosts `localhost`,
+  `127.0.0.1` or `[::1]`. Every request remains bound to the configured origin and uses
+  `redirect: error`, so a per-call override or redirect cannot move the service key to another
+  origin. It does not expose or simulate partner OAuth.
+- `createPublicClient` covers health and unauthenticated identity bootstrap. Public and dashboard
+  transports accept HTTPS or a browser-relative same-origin base URL; development HTTP requires the
+  explicit loopback-only opt-in used by the privileged clients.
+- `createDashboardV2Client` (also `createDashboardContractClient`) uses the browser session plus
+  CSRF for the dashboard projection. Both dashboard factories accept `expectedProviderBindingId`, a
+  selector-aware supplier used only for the exact BYO binding mutation path. Returning the current
+  secret-free binding UUID adds the `X-OxChannels-Expected-Binding-Id` compare-and-set header;
+  returning `undefined` performs initial binding creation. Malformed values and supplier failures
+  stop before transport.
+- `createAgentBootstrapClient` covers only the one-time Local Agent enrollment surface, with the
+  same HTTPS, configured-origin and `redirect: error` boundary as the partner client.
+
+Every client overwrites `OxChannels-Contract-Set` with the exact value `2.0.0` on every request.
+The raw OpenAPI keeps that header required for fetch operations, while the SDK projection removes it
+from caller-facing types; dashboard mutation types similarly omit the SDK-managed CSRF header.
+Operations marked `x-oxchannels-browser-navigation-only` (local sign-in, social sign-in start and
+callback, the MCP authorization front door and the provider OAuth callback) are removed from the
+fetch projections: callers must navigate the browser to those redirect endpoints. The generator
+requires those exact public GET operations, a sole `302` success and a required `Location` header;
+missing or unknown markers fail generation.
+
+Dashboard mutations fail before transport unless the configured CSRF supplier returns a safe value
+of at least 16 characters, while reads do not require one. Partner, public and agent clients
+explicitly omit browser credentials; only the dashboard client includes its session cookie. All
+clients force `redirect: error`, the exact configured origin and the expected credentials mode.
+Per-call base URL, redirect, credentials or transport overrides are rejected before an
+authentication or CSRF supplier is read; SDK-managed credentials are attached only after request
+middleware has completed.
+
+## Errors
+
+A v2 error is parsed by the canonical browser-safe parser (copied by the generator from
+`packages/contracts/src/api-errors.ts` into `src/generated/contracts/`, so the published package has
+no workspace dependency) and thrown as `OxChannelsApiErrorV2`, preserving the stable `code`,
+`category`, trace and correlation IDs, `retryable`, `effectEvidence`, optional `retryAfterSeconds`
+and bounded validation `violations`. The parsed code must also match the HTTP status contract
+(`409` allows only the two conflict variants, `5xx` only the safe internal variant, unlisted `4xx`
+only validation); a mismatch, malformed body or oversized error becomes
+`OxChannelsApiProtocolError`. Response bodies and service keys are never copied into that error.
+Error bodies are streamed into a strict 64 KiB budget and the stream is cancelled on overflow. The
+unauthorized hook runs only after a canonical `AUTHENTICATION_REQUIRED` response is parsed. Caller
+abort signals are combined with, and cannot disable, the SDK timeout (15 s by default, at most
+120 s); the timeout is released only when the response body reaches EOF or is cancelled. The
+legacy `OxChannelsApiError` remains as the base class.
+
+None of the wrappers retries writes; recovery continues to use explicit idempotency lookup and
+operation status. See `docs/guides/idempotency.md` in the OxChannels repository and the
+"Idempotency and retries" section of `QUICKSTART.md`.
+
+## Generated sources and provenance
+
+`pnpm openapi:generate` (from the repository root) regenerates the four projections, copies the two
+contract runtime sources and writes `generated/provenance.json` with separate source and output
+SHA-256 values. `pnpm openapi:check` rejects a missing projection, provenance drift, trust-surface
+drift, fake `/v2` wire paths, a v2 operation without the mandatory contract-set header, and a
+runtime-source copy that no longer matches its origin.
+
+Projections are generated with `immutable: false` on purpose: `openapi-fetch` only recognises
+mutable arrays when it derives the `data` type, so a `readonly` projection would leave response
+arrays without `map`, `find` or iteration. Request bodies therefore expect plain arrays; spread a
+`readonly` array before passing it.
+
+## Versioning and release
+
+The package version (`1.0.0` first) is independent of the sealed contract distribution recorded in
+`contracts.lock.json`. `.github/workflows/release-sdk.yml` builds, tests, compares the four
+contracts of the previously published tarball with the current documents to classify the semver
+level (`scripts/contracts/diff-surface.mjs`), publishes with `pnpm publish --access public` and
+tags `sdk-v<version>`. Pack and publish go through pnpm, never npm: the manifest uses the
+`catalog:` and `workspace:` protocols and only pnpm rewrites them to concrete versions. The
+`prepack` script copies the contracts and the licence into the package directory; both are
+git-ignored there. Details in
+`docs/guides/contract-versioning.md` in the OxChannels repository.
+
+## Development
+
+```bash
+pnpm --filter @oxchannels/sdk build   # tsc -> dist/
+pnpm --filter @oxchannels/sdk test    # runtime tests + type test of the example and consumer
+pnpm --filter @oxchannels/sdk lint
+cd packages/openapi-client && pnpm pack --pack-destination /tmp/sdk-pack
+```