@oxchannels/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Ox Studio
+
+All rights reserved.
+
+This source code and its documentation are proprietary and confidential. No
+permission is granted to use, copy, modify, distribute, sublicense, or publish
+this software without prior written authorization from the copyright holder.

package/QUICKSTART.md

@@ -0,0 +1,604 @@
+# SDK quickstart
+
+Status: **PRODUCTION_RELEASE_SDK_1_0**
+Reviewed: **2026-09-06**
+Owners: **API and Integration Lead**
+
+This guide takes an external system from `npm install` to a post published on every target a
+workspace can publish to, through `@oxchannels/sdk`. It uses the partner surface only: one service
+key, HTTPS, no browser, no OAuth. Every path and field below is taken from the sealed partner
+contract; the complete program is
+[`packages/openapi-client/examples/publish-everywhere.ts`](../../packages/openapi-client/examples/publish-everywhere.ts),
+which the package type-checks on every test run, so this page cannot describe a call the SDK does
+not have.
+
+<!-- generated:distribution-identity start -->
+
+| Property                | Value                            |
+| ----------------------- | -------------------------------- |
+| Sealed distribution     | `1.15.0`                         |
+| Contract set            | `2.0.0`                          |
+| Wire version            | `v1`                             |
+| Published operations    | 442                              |
+| Required version header | `OxChannels-Contract-Set: 2.0.0` |
+
+<!-- generated:distribution-identity end -->
+
+## 1. Install and create the client
+
+```bash
+npm install @oxchannels/sdk
+```
+
+OxChannels is in a closed beta: the package is public on npm, but every call needs an API key
+issued by the OxChannels team for your workspace, and contracts may still change between beta
+releases. This guide ships inside the package as `QUICKSTART.md`.
+
+The SDK is ESM only and needs a runtime with WHATWG `fetch` (Node 24 is what it is tested on). One
+client per service key; the key is created in the panel under API keys and is passed to the SDK as
+`serviceKey`. The SDK adds `Authorization: Bearer ...` and `OxChannels-Contract-Set: 2.0.0` to
+every request and refuses any base URL that is not HTTPS (except exact loopback hosts, behind an
+explicit opt-in).
+
+```ts
+import { createOxStudioClient } from '@oxchannels/sdk';
+
+const client = createOxStudioClient({
+  baseUrl: 'https://api.oxchannels.com',
+  serviceKey: () => process.env.OXS_API_KEY!,
+  correlationId: () => crypto.randomUUID(),
+});
+```
+
+Every non-2xx response is thrown as `OxChannelsApiErrorV2` (with the stable `code`, `retryable`,
+`effectEvidence`, trace and correlation IDs), so whenever a call returns, `data` is the typed
+success body.
+
+## 2. Confirm the key: `GET /v1/client-context`
+
+The first request tells you which workspace the key belongs to and which scopes it carries.
+Publishing needs `context:read` (both context reads) and `operations:write` (media, publications
+and actions); webhooks need `webhooks:manage`. A key without a scope fails the guarded operation
+with `FORBIDDEN`, so check up front.
+
+```ts
+const { data: me } = await client.GET('/v1/client-context');
+// me.workspace.id, me.client.scopes, me.entitlements
+```
+
+## 3. Where can this workspace publish: `GET /v1/integration/publishing-context`
+
+One read returns profiles, account groups and every target with its readiness and, for `READY`
+targets, the capability snapshot the platform will hold you to:
+
+| Field                    | Meaning                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `targets[].readiness`    | `READY`, `NEEDS_ATTENTION` or `UNAVAILABLE`; only `READY` targets accept publications                   |
+| `targets[].blocker`      | For the other two: a closed code plus a `remedy` (`FIX_IN_OXCHANNELS`, `RETRY_LATER`, ...)              |
+| `targets[].capability`   | `generation` and `snapshotHash` you must echo back, plus `featureCodes` (`TEXT`, `IMAGE`, `VIDEO`, ...) |
+| `targets[].connectorKey` | Provider key (`facebook`, `mastodon`, `youtube`, ...)                                                   |
+| `observedAt`             | When this snapshot was taken                                                                            |
+
+The snapshot is not a cache to keep: it changes whenever the provider connection is refreshed and a
+capability changes, and a publication built on an old one is refused (section 9).
+
+## 4. Upload media once: `POST /v1/integration/media`, upload, `finalize`
+
+Media is uploaded once per workspace and referenced by id from any number of publications:
+
+1. `POST /v1/integration/media` with `byteLength`, `detectedMime`, `sha256` (base64url of the
+   raw SHA-256) and an optional `clientReference`. The response is the asset (`id`, `state`) plus a
+   short-lived `uploadUrl` and the `requiredHeaders` the object store insists on.
+2. `PUT` the bytes to `uploadUrl` with exactly those headers.
+3. `POST /v1/integration/media/{mediaAssetId}/finalize`.
+4. Poll `GET /v1/integration/media/{mediaAssetId}` until `state` is `READY`. After `finalize` the
+   asset passes through `QUARANTINED` and `SCANNING`; `REJECTED` and `PURGED` are terminal.
+
+A publication that references an asset which is not `READY` is refused, so wait before section 5.
+Assets larger than one request use the multipart operations under
+`/v1/integration/media/multipart`; a file that already sits behind a public URL can be pulled by the
+platform with `POST /v1/integration/media/url-acquisitions`.
+
+How the bytes reach the provider is not your concern, but it explains the readiness blockers you
+may see. Each provider declares its media modes in the channel catalogue
+(`packages/channel-catalog/src/source.ts`, `capabilityDefaults.mediaModes`):
+
+| Provider          | Media modes                        | What the platform does with your asset                         |
+| ----------------- | ---------------------------------- | -------------------------------------------------------------- |
+| `facebook`        | `PUBLIC_URL`, `CONTAINER_ASYNC`    | Provider fetches from a public URL, then processes a container |
+| `instagram`       | `PUBLIC_URL`, `CONTAINER_ASYNC`    | Provider fetches from a public URL, then processes a container |
+| `threads`         | `PUBLIC_URL`, `CONTAINER_ASYNC`    | Provider fetches from a public URL, then processes a container |
+| `tiktok`          | `PUBLIC_URL`, `CONTAINER_ASYNC`    | Provider fetches from a public URL, then processes a container |
+| `pinterest`       | `PUBLIC_URL`, `MULTIPART`          | Provider fetches from a public URL, or chunked upload          |
+| `google-business` | `PUBLIC_URL`                       | Provider fetches from a public URL                             |
+| `site-plugin`     | `PUBLIC_URL`                       | Your site fetches from a public URL                            |
+| `bluesky`         | `BINARY_STREAM`, `CONTAINER_ASYNC` | Platform streams the bytes; video goes through a container     |
+| `snapchat`        | `BINARY_STREAM`, `CONTAINER_ASYNC` | Platform streams the bytes; video goes through a container     |
+| `linkedin`        | `BINARY_STREAM`, `RESUMABLE`       | Platform streams the bytes, resumable for large files          |
+| `mastodon`        | `BINARY_STREAM`                    | Platform streams the bytes                                     |
+| `reddit`          | `BINARY_STREAM`                    | Platform streams the bytes                                     |
+| `telegram`        | `BINARY_STREAM`                    | Platform streams the bytes                                     |
+| `whatsapp`        | `BINARY_STREAM`                    | Platform streams the bytes                                     |
+| `x-twitter`       | `CONTAINER_ASYNC`                  | Chunked provider upload, processed asynchronously              |
+| `youtube`         | `RESUMABLE`                        | Resumable provider upload                                      |
+| `discord`         | `MULTIPART`                        | Chunked provider upload                                        |
+
+`PUBLIC_URL` providers download from the platform's media host, which is why a workspace that
+publishes images to Meta or TikTok needs a public media domain configured on the deployment; the
+other modes never expose your asset by URL.
+
+## 5. One publication per target: `POST /v1/integration/publications`
+
+A publication is the content variant for one target, built against the capability you were shown:
+
+```ts
+const { data: 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: [imageAssetId],
+    options: { publishVariant: 'IMAGE' },
+    clientReference: `${workflowRunId}:${workflowTaskId}:${target.targetId}`,
+  },
+});
+// publication.item.id, publication.revision.id, publication.replayed
+```
+
+- `capabilityGeneration` and `capabilityHash` are the two values from section 3. They are the
+  contract: if the target's snapshot moved since you read it, the request is refused rather than
+  published against limits the channel no longer has.
+- `options` is the closed per-provider metadata object (title, privacy, first comment, thread
+  items, ...). Anything the provider does not accept is rejected before the effect.
+- `options.publishVariant` is required whenever the target's capability snapshot lists
+  `publishVariants`, and every official connector does (`TEXT`, `FEED`, `IMAGE`, `PHOTO`,
+  `PHOTO_DRAFT`, `VIDEO`, ...). The list lives in the target catalog, `GET /v1/targets`
+  (scope `targets:read`, field `official[].capabilitySnapshot.limits.publishVariants`), not in the
+  publishing context. A missing or unlisted variant is refused as `NOT_FOUND` without further
+  detail, so pick the variant before you build the publication: text only -> `TEXT` (Facebook:
+  `FEED`), one image -> `IMAGE` (Facebook: `PHOTO`, TikTok: `PHOTO` or `PHOTO_DRAFT`).
+- TikTok additionally requires the creator's decisions in `options`: `privacyLevel` (one of the
+  values in `publishChoices.privacyLevel`), `disableComment`, `brandContent`, `brandOrganic`.
+  A `PHOTO_DRAFT` accepts only `privacyLevel: 'SELF_ONLY'`, interactions disabled and all
+  disclosures `false`.
+- Image bytes: send JPEG when the same asset goes to Instagram or TikTok; their
+  `allowedMimeTypes` do not include `image/png`, and the mismatch is refused here, at publication
+  creation, not at publish time.
+- `clientReference` makes the create idempotent: the same reference with the same body replays the
+  earlier publication (`replayed: true`); the same reference with a different body is
+  `IDEMPOTENCY_CONFLICT`. Include the target id in it, because the fingerprint covers the target.
+
+## 6. Submit the action: `POST /v1/integration/publishing-actions`
+
+An action fans one content revision out to its targets. The response is `202 Accepted` with the
+per-target ledger the action will be reported through:
+
+```ts
+const { data: 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,
+      workflowTaskId,
+      taskGeneration: 1,
+    },
+  },
+});
+// action.actionId, action.outcome ('ACCEPTED' | 'IN_PROGRESS' | ...), action.targets[]
+```
+
+- `targetIds` takes between 1 and 20 distinct ids, each of which must have a variant on that
+  revision. A partner publication produces a revision with exactly one variant, so submit one action
+  per publication; a target without a variant is reported as `REJECTED` with `VARIANT_MISSING`,
+  it does not fail the whole action.
+- `mode` is `PUBLISH_NOW`, `SCHEDULE` (add `schedule`: civil time, time zone, DST policy, late
+  window) or `QUEUE` (add `queue`).
+- `oxStudioRun` is your idempotency identity (section 9).
+
+## 7. Follow it: `GET /v1/integration/publishing-actions/{actionId}`
+
+Poll until `outcome` is terminal: `SUCCEEDED`, `PARTIALLY_SUCCEEDED` or `FAILED`
+(`ACCEPTED` and `IN_PROGRESS` are not). Each entry in `targets[]` settles on its own lane with a
+`state` (`PENDING`, `ACCEPTED`, `SUCCEEDED`, `FAILED`, `REJECTED`, `UNKNOWN`), `retryable`, and on
+failure a closed `failure.code` with a `remedy`. `UNKNOWN` means the platform lost the provider's
+answer after the effect may have started; it is reconciled, never blindly retried, and
+`POST .../publishing-actions/{actionId}/retry` is the only way to try again.
+
+## 8. Stop polling: `POST /v1/webhook-subscriptions`
+
+```ts
+const { data: subscription } = await client.POST('/v1/webhook-subscriptions', {
+  body: {
+    destinationUrl: 'https://example.com/oxchannels/events',
+    eventAllowlist: ['operation.status.changed.v1'],
+  },
+});
+// subscription.id, subscription.signingSecret (shown exactly once), subscription.currentKeyId
+```
+
+`operation.status.changed.v1` fires for every operation state change behind your actions. The
+`signingSecret` is revealed once; store it before the response is gone. Delivery is at-least-once
+and signed; the envelope, the signature bytes and the replay rules are in
+[Webhooks](./webhooks.md). Keep a reconciliation pass on section 7 regardless: a webhook is a
+latency optimisation over state you can already read.
+
+## 9. Stale snapshots, retries and idempotency
+
+Two places tell you the capability you built on has moved:
+
+- `POST /v1/integration/publications` answers `404 NOT_FOUND` when the target no longer has the
+  snapshot (`capabilityGeneration` plus `capabilityHash`) you sent, or is no longer active. Re-read
+  the publishing context, take the target's new `capability`, and create the publication again.
+  The example does exactly this, once per target.
+- An already accepted action can settle a target as `FAILED` with `failure.code`
+  `CAPABILITY_STALE` and `remedy` `REBUILD_VARIANT`: create a new publication for that target from
+  a fresh context and submit a new action for it.
+
+Retries are safe because every write is idempotent on something you own:
+
+| Write              | Key                                                                 | Replay answer                     |
+| ------------------ | ------------------------------------------------------------------- | --------------------------------- |
+| media create       | `clientReference`                                                   | the existing asset                |
+| publication create | `clientReference` (include the target id)                           | `replayed: true`, same revision   |
+| publishing action  | `oxStudioRun` (`workflowRunId`, `workflowTaskId`, `taskGeneration`) | `replayed: true`, same `actionId` |
+
+A plain retry after a timeout keeps all three `oxStudioRun` values, so the derived key stays
+stable and you get the earlier action back. Bump `taskGeneration` only when you deliberately
+abandon the previous attempt; the same task with a different revision under the same generation is
+`409 IDEMPOTENCY_CONFLICT`. The wider rules (`retryable`, `effectEvidence`, what never to retry)
+are in [Idempotency and retries](./idempotency.md).
+
+## The complete program
+
+`packages/openapi-client/examples/publish-everywhere.ts`, verbatim:
+
+```ts
+/**
+ * Publish one post to every ready target of a workspace through `@oxchannels/sdk`.
+ *
+ * This file is the single source for the code shown in `README.md` and in
+ * `docs/guides/sdk-quickstart.md`; it is type-checked by `pnpm test` against the built package.
+ * Every path and field below comes from the sealed partner contract
+ * (`src/generated/partner-contract-v2-schema.ts`), so a contract change that would break a
+ * consumer breaks this example first.
+ *
+ * Run it with Node 24 after `npm install @oxchannels/sdk`:
+ *
+ *   OXS_API_KEY=... node --experimental-strip-types publish-everywhere.ts
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import {
+  OxChannelsApiErrorV2,
+  createOxStudioClient,
+  type OxStudioClient,
+  type PartnerContractV2Paths,
+} from '@oxchannels/sdk';
+
+type PublishingContext =
+  PartnerContractV2Paths['/v1/integration/publishing-context']['get']['responses'][200]['content']['application/json'];
+type PublishingTarget = PublishingContext['targets'][number];
+type PublishingAction =
+  PartnerContractV2Paths['/v1/integration/publishing-actions/{actionId}']['get']['responses'][200]['content']['application/json'];
+
+export interface PublishEverywhereInput {
+  /** `https://api.oxchannels.com` in production. HTTP is refused except for exact loopback hosts. */
+  readonly baseUrl: string;
+  /** Service key created in the panel (API keys). Passed to the SDK as `serviceKey`. */
+  readonly apiKey: string;
+  /** Post text; the per-target limits come back in the publishing context. */
+  readonly body: string;
+  /** BCP 47 tag, for example `en` or `pl`. */
+  readonly locale: string;
+  /** Optional local image to attach to every target that accepts media. */
+  readonly image?: { readonly path: string; readonly mime: string };
+  /** Optional HTTPS endpoint that should receive `operation.status.changed.v1`. */
+  readonly webhookUrl?: string;
+  /**
+   * Your own execution identity. The action's idempotency key is derived from it, so a plain
+   * retry keeps the same three values and a deliberate re-run bumps `taskGeneration`.
+   */
+  readonly run: {
+    readonly workflowRunId: string;
+    readonly workflowTaskId: string;
+    readonly taskGeneration: number;
+  };
+}
+
+export interface PublishEverywhereResult {
+  readonly targetId: string;
+  readonly connectorKey: string;
+  readonly actionId: string | null;
+  readonly outcome: PublishingAction['outcome'] | 'SKIPPED';
+  readonly detail: string;
+}
+
+const POLL_INTERVAL_MS = 1_000;
+const MAX_POLLS = 120;
+const TERMINAL_OUTCOMES: ReadonlySet<PublishingAction['outcome']> = new Set([
+  'SUCCEEDED',
+  'PARTIALLY_SUCCEEDED',
+  'FAILED',
+]);
+
+function required<T>(value: T | undefined, what: string): T {
+  if (value === undefined) throw new Error(`${what}: the API returned no body`);
+  return value;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** 1. One client per service key. The SDK sets `OxChannels-Contract-Set` and `Authorization`. */
+export function createClient(input: PublishEverywhereInput): OxStudioClient {
+  return createOxStudioClient({
+    baseUrl: input.baseUrl,
+    serviceKey: () => input.apiKey,
+    correlationId: () => randomUUID(),
+  });
+}
+
+/** 2. Who am I, and what may this key do? Fails fast on a wrong key or missing scope. */
+export async function readClientContext(client: OxStudioClient) {
+  const context = required((await client.GET('/v1/client-context')).data, 'GET /v1/client-context');
+  return { workspaceId: context.workspace.id, scopes: context.client.scopes };
+}
+
+/** 3. Where can this workspace publish right now? Only `READY` targets carry a capability. */
+export async function readPublishingContext(client: OxStudioClient): Promise<PublishingContext> {
+  return required(
+    (await client.GET('/v1/integration/publishing-context')).data,
+    'GET /v1/integration/publishing-context',
+  );
+}
+
+/**
+ * 4. Upload media once, reuse the asset id for every target. The asset is scanned after
+ * `finalize`; publish only after it reports `READY`.
+ */
+export async function uploadImage(
+  client: OxStudioClient,
+  image: NonNullable<PublishEverywhereInput['image']>,
+): Promise<string> {
+  const bytes = await readFile(image.path);
+  const created = required(
+    (
+      await client.POST('/v1/integration/media', {
+        body: {
+          byteLength: bytes.byteLength,
+          detectedMime: image.mime,
+          sha256: createHash('sha256').update(bytes).digest('base64url'),
+          clientReference: `image:${image.path}`,
+        },
+      })
+    ).data,
+    'POST /v1/integration/media',
+  );
+  if (created.uploadUrl === undefined) {
+    throw new Error(`media ${created.id} is ${created.state} and has no upload grant`);
+  }
+  const upload = await fetch(created.uploadUrl, {
+    method: 'PUT',
+    headers: created.requiredHeaders ?? {},
+    body: bytes,
+  });
+  if (!upload.ok) throw new Error(`object store rejected the upload: HTTP ${upload.status}`);
+
+  await client.POST('/v1/integration/media/{mediaAssetId}/finalize', {
+    params: { path: { mediaAssetId: created.id } },
+  });
+  for (let attempt = 0; attempt < MAX_POLLS; attempt += 1) {
+    const asset = required(
+      (
+        await client.GET('/v1/integration/media/{mediaAssetId}', {
+          params: { path: { mediaAssetId: created.id } },
+        })
+      ).data,
+      'GET /v1/integration/media/{mediaAssetId}',
+    );
+    if (asset.state === 'READY') return asset.id;
+    if (asset.state === 'REJECTED' || asset.state === 'PURGED') {
+      throw new Error(`media ${asset.id} ended in state ${asset.state}`);
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(`media ${created.id} did not become READY in time`);
+}
+
+/**
+ * 5. One publication per target. The request carries the capability generation and hash the
+ * context reported for that target, so the platform can refuse content built against a stale
+ * snapshot instead of publishing something the channel no longer accepts.
+ */
+export async function createPublication(
+  client: OxStudioClient,
+  input: PublishEverywhereInput,
+  target: PublishingTarget,
+  mediaAssetIds: readonly string[],
+): Promise<string> {
+  if (target.capability === null) throw new Error(`target ${target.targetId} has no capability`);
+  const publication = required(
+    (
+      await client.POST('/v1/integration/publications', {
+        body: {
+          targetId: target.targetId,
+          capabilityGeneration: target.capability.generation,
+          capabilityHash: target.capability.snapshotHash,
+          body: input.body,
+          locale: input.locale,
+          mediaAssetIds: [...mediaAssetIds],
+          options: {},
+          clientReference: `${input.run.workflowRunId}:${input.run.workflowTaskId}:${target.targetId}`,
+        },
+      })
+    ).data,
+    'POST /v1/integration/publications',
+  );
+  return publication.revision.id;
+}
+
+/** 6. Submit the action and 7. poll it until every target settled. */
+export async function submitAndAwaitAction(
+  client: OxStudioClient,
+  input: PublishEverywhereInput,
+  contentRevisionId: string,
+  targetIds: readonly string[],
+): Promise<PublishingAction> {
+  const accepted = required(
+    (
+      await client.POST('/v1/integration/publishing-actions', {
+        body: {
+          mode: 'PUBLISH_NOW',
+          contentRevisionId,
+          targetIds: [...targetIds],
+          oxStudioRun: { schemaVersion: 'ox-studio-run.v1', ...input.run },
+        },
+      })
+    ).data,
+    'POST /v1/integration/publishing-actions',
+  );
+  let action: PublishingAction = accepted;
+  for (
+    let attempt = 0;
+    attempt < MAX_POLLS && !TERMINAL_OUTCOMES.has(action.outcome);
+    attempt += 1
+  ) {
+    await sleep(POLL_INTERVAL_MS);
+    action = required(
+      (
+        await client.GET('/v1/integration/publishing-actions/{actionId}', {
+          params: { path: { actionId: accepted.actionId } },
+        })
+      ).data,
+      'GET /v1/integration/publishing-actions/{actionId}',
+    );
+  }
+  return action;
+}
+
+/** 8. Ask to be told instead of polling. Keep `signingSecret`: it is shown exactly once. */
+export async function subscribeToOperationChanges(
+  client: OxStudioClient,
+  destinationUrl: string,
+): Promise<{ subscriptionId: string; signingSecret: string }> {
+  const subscription = required(
+    (
+      await client.POST('/v1/webhook-subscriptions', {
+        body: { destinationUrl, eventAllowlist: ['operation.status.changed.v1'] },
+      })
+    ).data,
+    'POST /v1/webhook-subscriptions',
+  );
+  return { subscriptionId: subscription.id, signingSecret: subscription.signingSecret };
+}
+
+function isStaleSnapshot(error: unknown): boolean {
+  // A publication built against a snapshot the target no longer has is refused as NOT_FOUND
+  // (the closed error set has no dedicated code for it yet). Re-read the context and retry once.
+  return error instanceof OxChannelsApiErrorV2 && error.code === 'NOT_FOUND';
+}
+
+export async function publishEverywhere(
+  input: PublishEverywhereInput,
+): Promise<readonly PublishEverywhereResult[]> {
+  const client = createClient(input);
+  const { scopes } = await readClientContext(client);
+  for (const scope of ['context:read', 'operations:write']) {
+    if (!scopes.includes(scope)) throw new Error(`service key lacks the ${scope} scope`);
+  }
+
+  let context = await readPublishingContext(client);
+  const mediaAssetIds = input.image === undefined ? [] : [await uploadImage(client, input.image)];
+  const results: PublishEverywhereResult[] = [];
+
+  for (const initialTarget of context.targets) {
+    let target: PublishingTarget = initialTarget;
+    if (target.readiness !== 'READY' || target.capability === null) {
+      results.push({
+        targetId: target.targetId,
+        connectorKey: target.connectorKey,
+        actionId: null,
+        outcome: 'SKIPPED',
+        detail:
+          target.blocker === null
+            ? target.readiness
+            : `${target.blocker.code}: ${target.blocker.remedy}`,
+      });
+      continue;
+    }
+    const attachMedia = target.capability.featureCodes.includes('IMAGE') ? mediaAssetIds : [];
+
+    let contentRevisionId: string;
+    try {
+      contentRevisionId = await createPublication(client, input, target, attachMedia);
+    } catch (error) {
+      if (!isStaleSnapshot(error)) throw error;
+      context = await readPublishingContext(client);
+      const refreshed = context.targets.find((candidate) => candidate.targetId === target.targetId);
+      if (refreshed === undefined || refreshed.readiness !== 'READY') {
+        results.push({
+          targetId: target.targetId,
+          connectorKey: target.connectorKey,
+          actionId: null,
+          outcome: 'SKIPPED',
+          detail: 'target disappeared or lost readiness while publishing',
+        });
+        continue;
+      }
+      target = refreshed;
+      contentRevisionId = await createPublication(client, input, target, attachMedia);
+    }
+
+    // Each partner publication yields a revision with one target variant, so one action per
+    // revision. The endpoint itself accepts up to 20 target ids when a revision carries a
+    // variant for each of them.
+    const action = await submitAndAwaitAction(client, input, contentRevisionId, [target.targetId]);
+    const settled = action.targets.find((entry) => entry.targetId === target.targetId);
+    results.push({
+      targetId: target.targetId,
+      connectorKey: target.connectorKey,
+      actionId: action.actionId,
+      outcome: action.outcome,
+      detail:
+        settled?.failure === null || settled?.failure === undefined
+          ? (settled?.state ?? 'UNKNOWN')
+          : `${settled.failure.code}: ${settled.failure.remedy}`,
+    });
+  }
+
+  if (input.webhookUrl !== undefined) {
+    const subscription = await subscribeToOperationChanges(client, input.webhookUrl);
+    console.log(`webhook ${subscription.subscriptionId} created; store the signing secret now`);
+  }
+  return results;
+}
+
+if (process.env['OXS_API_KEY'] !== undefined) {
+  const results = await publishEverywhere({
+    baseUrl: process.env['OXS_API_BASE'] ?? 'https://api.oxchannels.com',
+    apiKey: process.env['OXS_API_KEY'],
+    body: 'Hello from @oxchannels/sdk',
+    locale: 'en',
+    run: { workflowRunId: randomUUID(), workflowTaskId: 'publish-everywhere', taskGeneration: 1 },
+  });
+  for (const result of results) {
+    console.log(`${result.connectorKey} ${result.targetId}: ${result.outcome} (${result.detail})`);
+  }
+}
+```
+
+## What this guide does not give you
+
+- Connecting a provider account. Targets appear in the publishing context only after a connection
+  exists and its capability snapshot is fresh; that happens in the panel or through
+  [Headless connect](./headless-connect.md).
+- Any promise that a channel is live for your workspace. `readiness` and `blocker` are the truth
+  for right now; the sealed contract only promises the shape of the answer.
+- Exactly-once delivery. Every layer here is at-least-once with idempotency on your identifiers,
+  see section 9.