@outposted/node 0.1.0

package/src/resources/contents.ts

@@ -0,0 +1,424 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/resources/contents — Content publishing surface.
+//
+// A Content is one publish intent that fans out into N Jobs (one per target
+// platform). The API contract (apps/api/.../contents) is the source of truth;
+// shapes here mirror what the routes emit. We intentionally re-export the
+// canonical domain types (`Content`, `ContentPayload`, `MediaItem`, etc) via
+// type-only imports from @outposted/domain so the SDK and the API can never
+// drift apart.
+//
+// Endpoints proxied here:
+//   - POST   /v1/workspaces/:wsId/contents               → create + dispatch
+//   - GET    /v1/workspaces/:wsId/contents               → list summaries
+//   - GET    /v1/workspaces/:wsId/contents/:contentId    → fetch one + jobs
+//   - DELETE /v1/workspaces/:wsId/contents/:contentId    → cancel (idempotent)
+//   - POST   /v1/workspaces/:wsId/contents/:contentId/retry → re-attempt publish
+//
+// Note: the API exposes cancel as `DELETE /contents/:id` (no `/cancel` suffix).
+// The SDK still names the method `cancel(...)` because that's what consumers
+// reach for — the HTTP verb is an implementation detail.
+//
+// Response shapes are unwrapped at the boundary. `list` returns
+// `{ data, pagination }` from the API as `{ items, total }` so the caller
+// works with a flat shape (and `total` is the only pagination field most
+// callers need; limit/offset they passed themselves).
+// ────────────────────────────────────────────────────────────────────────────
+
+import type {
+  Content,
+  ContentPayload,
+  ContentStatus,
+  ContentType,
+} from '@outposted/domain';
+import type { HttpClient } from '../transport';
+
+/**
+ * Body accepted by `ContentsResource.create`. Mirrors the POST body the API
+ * expects (`workspace_id` is taken from the URL, so we omit it here).
+ *
+ * `target_connections` is optional — the API auto-resolves a single connection
+ * per target platform when omitted. Pass an explicit list of
+ * `connected_account.id` values when a brand has ≥2 connections on a platform
+ * (otherwise the API returns 422 `connections_required`).
+ *
+ * `schedule_at` is optional ISO-8601 — omit for immediate publish.
+ */
+export interface ContentCreateInput {
+  brand_id: string;
+  content_type: ContentType;
+  target_platforms: string[];
+  /**
+   * Optional explicit disambiguator when a brand has multiple connections on
+   * one of the target platforms. Each entry MUST be a `connected_account.id`.
+   */
+  target_connections?: string[];
+  content: ContentPayload;
+  /** ISO-8601 UTC timestamp. Omit for immediate publish. */
+  schedule_at?: string;
+}
+
+/**
+ * Per-job summary embedded in the `create` and `get` responses — one row per
+ * target platform (or per target connection when disambiguated).
+ */
+export interface ContentJobSummary {
+  /** Job id in the create-response shape uses `job_id`; we expose it as `id` here. */
+  job_id: string;
+  platform: string;
+  status: string;
+}
+
+/**
+ * Per-slot upload descriptor returned by `create` when the request opted into
+ * direct-to-R2 large-media upload (`media[i].upload === true`). Clients PUT
+ * raw bytes to `upload_url`; the worker takes over once every slot lands.
+ */
+export interface ContentUploadSlot {
+  position: number;
+  r2_key: string;
+  upload_url: string;
+}
+
+/**
+ * Response from `ContentsResource.create`. The API returns ONE of two shapes
+ * depending on whether the request opted into direct large-media upload:
+ *
+ *   - `awaiting_media` branch: the client must PUT bytes to each
+ *     `uploads[i].upload_url`; jobs are dispatched once every slot lands.
+ *   - `queued` / `scheduled` branch: jobs were dispatched immediately (or
+ *     scheduled for `scheduled_at`).
+ *
+ * Both shapes share `content_id`, `status`, and `created_at`. The remaining
+ * fields are split via a discriminated union so TypeScript can narrow on
+ * `status`.
+ */
+export type ContentCreateResponse =
+  | {
+      content_id: string;
+      status: 'awaiting_media';
+      created_at: string;
+      uploads: ContentUploadSlot[];
+    }
+  | {
+      content_id: string;
+      status: 'queued' | 'scheduled';
+      created_at: string;
+      scheduled_at?: string;
+      jobs: ContentJobSummary[];
+    };
+
+/**
+ * Bandwidth-conscious summary returned by `list` — no full payload. Use `get`
+ * for the full payload + nested jobs.
+ *
+ * Mirrors `@outposted/domain` `ContentSummary`.
+ */
+export interface ContentSummary {
+  id: string;
+  brand_id: string;
+  content_type: ContentType;
+  status: ContentStatus;
+  target_platforms: string[];
+  jobs_count: number;
+  created_at: string;
+  scheduled_at: string | null;
+}
+
+/**
+ * Filters accepted by `ContentsResource.list`.
+ */
+export interface ContentListQuery {
+  status?: ContentStatus;
+  brand_id?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Detail shape returned by `get(contentId)`. The API rebuilds the payload from
+ * the persisted row and attaches the per-platform jobs; we surface that exactly
+ * as-is. Note this is a different shape from the canonical `Content` entity
+ * (which has no embedded `jobs`) — the API enriches it for clients.
+ */
+export interface ContentDetailJob {
+  id: string;
+  platform_slug: string;
+  provider_slug: string;
+  status: string;
+  external_post_id: string | null;
+  external_post_url: string | null;
+  error_code: string | null;
+  error_message: string | null;
+  attempt_count: number;
+  queued_at: string;
+  completed_at: string | null;
+  poll_count: number | null;
+  processing_ms: number | null;
+}
+
+/**
+ * Full content detail returned by `get(contentId)`. Note that this is a wire
+ * shape — it overlaps with the domain `Content` entity but adds `jobs`,
+ * `completed_at`, and optional `media`/`media_progress`. The `payload` is the
+ * publishable union of fields any platform might consume; see
+ * `ContentPayload` for the exhaustive list.
+ */
+export interface ContentDetail
+  extends Pick<
+    Content,
+    'id' | 'brand_id' | 'content_type' | 'status' | 'target_platforms' | 'created_at' | 'scheduled_at'
+  > {
+  payload: ContentPayload;
+  completed_at: string | null;
+  jobs: ContentDetailJob[];
+  media_progress?: { uploaded: number; total: number };
+  media?: Array<{
+    position: number;
+    media_type: 'image' | 'video';
+    status: string;
+    uploaded_at: string | null;
+  }>;
+}
+
+/**
+ * Cancel response shape. The API returns the same envelope for both the
+ * "actually cancelled now" and the idempotent "already cancelled" cases —
+ * callers can treat both as success.
+ */
+export interface ContentCancelResponse {
+  id: string;
+  status: 'cancelled';
+  scheduled_at: string | null;
+  cancelled_at: string | null;
+}
+
+/**
+ * Retry response shape. `retried_jobs` is the number of non-`published` jobs
+ * that were reset to `queued` (already-published jobs are left untouched).
+ */
+export interface ContentRetryResponse {
+  content_id: string;
+  status: 'queued';
+  retried_jobs: number;
+}
+
+interface ContentListEnvelope {
+  data: ContentSummary[];
+  pagination: { limit: number; offset: number; total: number };
+}
+
+/**
+ * SDK accessor for the `/v1/workspaces/:wsId/contents` collection. The core
+ * publishing surface of the SDK — `create` is what most callers exercise.
+ *
+ * @example
+ * ```ts
+ * const outposted = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+ * const result = await outposted.contents.create('ws_123', {
+ *   brand_id: 'brand_abc',
+ *   content_type: 'post',
+ *   target_platforms: ['instagram'],
+ *   content: {
+ *     caption: 'Hello from the SDK',
+ *     media: [{ type: 'image', url: 'https://cdn.example.com/cover.jpg' }],
+ *   },
+ * });
+ * ```
+ */
+export class ContentsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Create a Content and dispatch a publish (or schedule it). For
+   * `content_type: 'post'` on Instagram with an image URL, the API queues a
+   * single job and returns 202 with the job descriptor.
+   *
+   * Pass an `Idempotency-Key` header at the transport level if you need
+   * exactly-once semantics across retries (V0 only honours the API-side
+   * `Idempotency-Key`; the SDK does not auto-generate one).
+   *
+   * @example curl
+   * ```bash
+   * curl -X POST -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   -H "Content-Type: application/json" \
+   *   -d '{
+   *     "brand_id": "brand_abc",
+   *     "content_type": "post",
+   *     "target_platforms": ["instagram"],
+   *     "content": {
+   *       "caption": "Hello from curl",
+   *       "media": [{ "type": "image", "url": "https://cdn.example.com/cover.jpg" }]
+   *     }
+   *   }' \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/contents
+   * ```
+   *
+   * @example SDK (Instagram image post)
+   * ```ts
+   * const result = await outposted.contents.create('ws_123', {
+   *   brand_id: 'brand_abc',
+   *   content_type: 'post',
+   *   target_platforms: ['instagram'],
+   *   content: {
+   *     caption: 'Hello from the SDK',
+   *     media: [{ type: 'image', url: 'https://cdn.example.com/cover.jpg' }],
+   *   },
+   * });
+   * if (result.status !== 'awaiting_media') {
+   *   console.log(`queued ${result.jobs.length} job(s)`);
+   * }
+   * ```
+   *
+   * @example SDK (multi-connection disambiguation)
+   * ```ts
+   * await outposted.contents.create('ws_123', {
+   *   brand_id: 'brand_abc',
+   *   content_type: 'post',
+   *   target_platforms: ['linkedin'],
+   *   target_connections: ['conn_personal', 'conn_company'],
+   *   content: { text: 'Cross-posted to both LinkedIn surfaces' },
+   * });
+   * ```
+   *
+   * Throws `OutpostedValidationError` (HTTP 400/422) when payload shape is
+   * invalid, content-type/platform matrix is violated, per-platform specs
+   * fail, or multiple connections are available without an explicit
+   * `target_connections`.
+   */
+  async create(
+    workspaceId: string,
+    input: ContentCreateInput,
+  ): Promise<ContentCreateResponse> {
+    return this.http.request<ContentCreateResponse>({
+      method: 'POST',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/contents`,
+      body: input,
+    });
+  }
+
+  /**
+   * List contents in a workspace, newest first. Returns lightweight summaries
+   * (no full payload) — the API caps `limit` at 100 (default 50) and supports
+   * `status` / `brand_id` filters.
+   *
+   * Returns `{ items, total }` — the API envelope is unwrapped here so callers
+   * don't have to dig through `{ data, pagination }`.
+   *
+   * @example curl
+   * ```bash
+   * curl -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   "https://api.outposted.one/api/v1/workspaces/ws_123/contents?status=published&limit=20"
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const { items, total } = await outposted.contents.list('ws_123', {
+   *   status: 'published',
+   *   limit: 20,
+   * });
+   * console.log(`${items.length} of ${total}`);
+   * ```
+   */
+  async list(
+    workspaceId: string,
+    query?: ContentListQuery,
+  ): Promise<{ items: ContentSummary[]; total: number }> {
+    const response = await this.http.request<ContentListEnvelope>({
+      method: 'GET',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/contents`,
+      query: query
+        ? {
+            status: query.status,
+            brand_id: query.brand_id,
+            limit: query.limit,
+            offset: query.offset,
+          }
+        : undefined,
+    });
+    return { items: response.data, total: response.pagination.total };
+  }
+
+  /**
+   * Fetch a single content by id, including the rebuilt publishable payload
+   * and the nested per-platform jobs. The primary status-polling endpoint for
+   * V0 — webhook delivery (E2) lets you avoid polling in most flows.
+   *
+   * Throws `OutpostedNotFoundError` (HTTP 404) for missing or cross-tenant
+   * content ids (the API does not leak existence across workspaces).
+   *
+   * @example curl
+   * ```bash
+   * curl -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/contents/cnt_abc
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const content = await outposted.contents.get('ws_123', 'cnt_abc');
+   * console.log(content.status, content.jobs.length);
+   * ```
+   */
+  async get(workspaceId: string, contentId: string): Promise<ContentDetail> {
+    return this.http.request<ContentDetail>({
+      method: 'GET',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/contents/${encodeURIComponent(contentId)}`,
+    });
+  }
+
+  /**
+   * Cancel a queued or scheduled content. Idempotent — a second cancel on an
+   * already-cancelled content returns success (the API never 404s here).
+   *
+   * The underlying HTTP verb is `DELETE` (RESTful cancel semantics in the
+   * API); the SDK exposes it as `cancel(...)` because that's what consumers
+   * expect to call. Content in `publishing` returns 409
+   * `cancel_too_late` — surfaced here as `OutpostedConflictError`.
+   *
+   * @example curl
+   * ```bash
+   * curl -X DELETE -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/contents/cnt_abc
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * await outposted.contents.cancel('ws_123', 'cnt_abc');
+   * ```
+   */
+  async cancel(workspaceId: string, contentId: string): Promise<ContentCancelResponse> {
+    return this.http.request<ContentCancelResponse>({
+      method: 'DELETE',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/contents/${encodeURIComponent(contentId)}`,
+    });
+  }
+
+  /**
+   * Re-attempt publishing a content that failed, partially failed, or got
+   * stuck in `publishing` past the in-flight window. No media re-upload —
+   * the persisted payload (R2 URLs included) is reused.
+   *
+   * Only non-`published` jobs are reset; the response's `retried_jobs` is the
+   * count that were actually re-enqueued. Returns 409 `not_retryable` (via
+   * `OutpostedConflictError`) for terminal-success or actively-publishing
+   * content.
+   *
+   * @example curl
+   * ```bash
+   * curl -X POST -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/contents/cnt_abc/retry
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const { retried_jobs } = await outposted.contents.retry('ws_123', 'cnt_abc');
+   * console.log(`re-queued ${retried_jobs} job(s)`);
+   * ```
+   */
+  async retry(workspaceId: string, contentId: string): Promise<ContentRetryResponse> {
+    return this.http.request<ContentRetryResponse>({
+      method: 'POST',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/contents/${encodeURIComponent(contentId)}/retry`,
+    });
+  }
+}

package/src/resources/deliveries.ts

@@ -0,0 +1,186 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/resources/deliveries — Webhook delivery inspection + retry.
+//
+// A WebhookDelivery is one attempt to POST a signed payload at a webhook
+// endpoint. Each endpoint accumulates a delivery history (one row per
+// outbound POST) which the customer inspects to debug receiver failures and
+// manually re-queue stuck ones.
+//
+// Endpoints proxied here (see apps/api/src/app/api/v1/...):
+//   - GET  /v1/workspaces/:wsId/webhooks/:id/deliveries
+//        → list deliveries for an endpoint, paginated, filterable by status
+//          + since/until ISO windows. API envelope is `{ data, total, limit,
+//          offset }`; we map `data` → `items` for symmetry with the rest of
+//          the SDK (every list method returns `{ items, ... }`).
+//   - POST /v1/workspaces/:wsId/deliveries/:deliveryId/redeliver
+//        → re-queue a delivery for another attempt. Typically used on
+//          `failed` or `dlq` rows — the original payload and signing key are
+//          reused, so the receiver sees a byte-identical retry (same body,
+//          new timestamp/signature). 202 Accepted.
+//
+// Errors are surfaced as the typed OutpostedError subclasses produced by the
+// transport layer (e.g. OutpostedNotFoundError on 404).
+// ────────────────────────────────────────────────────────────────────────────
+
+import type { WebhookDelivery, WebhookDeliveryStatus } from '@outposted/domain';
+import type { HttpClient } from '../transport';
+
+/** Query params accepted by `DeliveriesResource.list`. */
+export interface DeliveriesListQuery {
+  /** Filter by terminal/in-flight state. Omit for "all statuses". */
+  status?: WebhookDeliveryStatus;
+  /** ISO-8601 datetime — only deliveries created at-or-after this instant. */
+  since?: string;
+  /** ISO-8601 datetime — only deliveries created at-or-before this instant. */
+  until?: string;
+  /** Page size, 1..100 (API default: 25). */
+  limit?: number;
+  /** Page offset, >=0 (API default: 0). */
+  offset?: number;
+}
+
+/**
+ * Paginated list of webhook deliveries. The `items` field is named `data` on
+ * the API wire — we rename it here so every SDK list method has a uniform
+ * `{ items, total, limit, offset }` shape.
+ */
+export interface DeliveriesListResult {
+  items: WebhookDelivery[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+/** Response shape returned by `POST .../redeliver` (HTTP 202). */
+export interface DeliveryRedeliverResult {
+  ok: boolean;
+  delivery_id: string;
+  /** Lifecycle hint — typically `"queued"` once the workflow trigger lands. */
+  status: string;
+}
+
+interface DeliveriesListWireResponse {
+  data: WebhookDelivery[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+/**
+ * SDK accessor for webhook delivery introspection and manual retry.
+ *
+ * @example
+ * ```ts
+ * const outposted = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+ *
+ * // Inspect the last 25 failed deliveries for an endpoint
+ * const { items } = await outposted.deliveries.list('ws_123', 'wh_456', {
+ *   status: 'failed',
+ * });
+ *
+ * // Force a retry on a single delivery
+ * await outposted.deliveries.redeliver('ws_123', items[0]!.id);
+ * ```
+ */
+export class DeliveriesResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List webhook deliveries for an endpoint, newest first.
+   *
+   * Supports status filtering plus a `since`/`until` ISO-8601 window for
+   * targeted post-incident audits. Pagination is offset-based; the response
+   * always echoes `limit`/`offset` so callers can drive a "load more"
+   * scroller without tracking client-side state.
+   *
+   * @example curl
+   * ```bash
+   * curl -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   "https://api.outposted.one/api/v1/workspaces/ws_123/webhooks/wh_456/deliveries?status=failed&limit=50"
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const page = await outposted.deliveries.list('ws_123', 'wh_456', {
+   *   status: 'dlq',
+   *   since: '2026-06-01T00:00:00.000Z',
+   *   limit: 50,
+   * });
+   * for (const delivery of page.items) {
+   *   console.log(delivery.id, delivery.last_response_status);
+   * }
+   * ```
+   *
+   * Throws `OutpostedNotFoundError` (404) if the endpoint id does not exist
+   * in the workspace, or `OutpostedValidationError` (400) if the query
+   * parameters are malformed (bad ISO date, status out of enum, etc.).
+   */
+  async list(
+    workspaceId: string,
+    webhookId: string,
+    query?: DeliveriesListQuery,
+  ): Promise<DeliveriesListResult> {
+    const path = `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/webhooks/${encodeURIComponent(webhookId)}/deliveries`;
+    const response = await this.http.request<DeliveriesListWireResponse>({
+      method: 'GET',
+      path,
+      query: {
+        status: query?.status,
+        since: query?.since,
+        until: query?.until,
+        limit: query?.limit,
+        offset: query?.offset,
+      },
+    });
+    return {
+      items: response.data,
+      total: response.total,
+      limit: response.limit,
+      offset: response.offset,
+    };
+  }
+
+  /**
+   * Force a new delivery attempt for a previously-attempted delivery.
+   *
+   * Typically used on `failed` or `dlq` rows after the receiver was fixed —
+   * the original signed payload is reused, so the customer receives a
+   * byte-identical retry (only the `t=` timestamp in `X-Outposted-Signature`
+   * changes, by design, since signatures bind the timestamp). The API
+   * returns 202 immediately; the actual POST runs asynchronously on the
+   * delivery worker.
+   *
+   * @example curl
+   * ```bash
+   * curl -X POST -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/deliveries/del_789/redeliver
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * // After fixing a receiver, replay every dlq delivery from yesterday
+   * const { items } = await outposted.deliveries.list('ws_123', 'wh_456', {
+   *   status: 'dlq',
+   *   since: '2026-06-02T00:00:00.000Z',
+   *   until: '2026-06-03T00:00:00.000Z',
+   * });
+   * for (const delivery of items) {
+   *   await outposted.deliveries.redeliver('ws_123', delivery.id);
+   * }
+   * ```
+   *
+   * Throws `OutpostedNotFoundError` (404) if the delivery id does not exist
+   * in the workspace, or `OutpostedServerError` (500) if the upstream queue
+   * (QStash) is misconfigured or rejected the trigger.
+   */
+  async redeliver(
+    workspaceId: string,
+    deliveryId: string,
+  ): Promise<DeliveryRedeliverResult> {
+    const path = `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/deliveries/${encodeURIComponent(deliveryId)}/redeliver`;
+    return this.http.request<DeliveryRedeliverResult>({
+      method: 'POST',
+      path,
+    });
+  }
+}