@outposted/node 0.1.0

package/src/index.ts

@@ -0,0 +1,37 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node — public entry point.
+// ────────────────────────────────────────────────────────────────────────────
+
+export { Outposted, type OutpostedOptions } from './client';
+
+export {
+  OutpostedError,
+  OutpostedAuthError,
+  OutpostedValidationError,
+  OutpostedForbiddenError,
+  OutpostedNotFoundError,
+  OutpostedConflictError,
+  OutpostedRateLimitError,
+  OutpostedServerError,
+  OutpostedNetworkError,
+  type OutpostedErrorOptions,
+  type OutpostedErrorBody,
+  type ValidationIssue,
+  type OutpostedValidationErrorOptions,
+  type OutpostedRateLimitErrorOptions,
+} from './errors';
+
+export { HttpClient, type HttpClientOptions, type RequestOptions, type FetchLike } from './transport';
+
+export { WorkspacesResource } from './resources/workspaces';
+export { BrandsResource } from './resources/brands';
+export { ApiKeysResource } from './resources/api-keys';
+export { ContentsResource } from './resources/contents';
+export { ConnectionsResource } from './resources/connections';
+export { WebhooksResource } from './resources/webhooks';
+export { DeliveriesResource } from './resources/deliveries';
+export { OAuthResource } from './resources/oauth';
+
+// Re-export webhook signing helpers so consumers don't have to install a
+// second package to verify incoming Outposted webhooks.
+export { signPayload, verifyPayload } from '@outposted/webhooks';

package/src/resources/api-keys.ts

@@ -0,0 +1,157 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/resources/api-keys — workspace API key management.
+//
+// Two operations, both scoped to a workspace:
+//
+//   - list(workspaceId)          GET  /v1/workspaces/:wsId/api-keys
+//   - rotate(workspaceId, body?) POST /v1/workspaces/:wsId/api-keys
+//
+// The server NEVER returns plaintext on list — only metadata (id, name, prefix,
+// timestamps). Plaintext is returned exactly ONCE, by `rotate()`, on the same
+// 201 response that creates the new key. There is no second chance: if the
+// caller drops the response, the key is unrecoverable.
+//
+// `revoke_others: true` is the proper rotation hygiene: create a new key, then
+// in the SAME atomic operation revoke every other active key in the workspace.
+// Use this on credential leak or scheduled rotation.
+// ────────────────────────────────────────────────────────────────────────────
+
+import type { HttpClient } from '../transport';
+
+/**
+ * Metadata for an API key as returned by `list()`. Contains NO secret material —
+ * neither the plaintext key nor its hash. `prefix` is the short, non-secret
+ * identifier (e.g. `opst_live_AbCd...`) safe to display in dashboards and logs.
+ */
+export interface ApiKey {
+  /** Stable identifier (e.g. `key_01HXY...`). */
+  id: string;
+  /** Human label set at creation time. Defaults to `"rotated"` when not provided. */
+  name: string;
+  /** Non-secret prefix safe to display (e.g. `opst_live_AbCd...`). */
+  prefix: string;
+  /** ISO-8601 timestamp the key was created. */
+  created_at: string;
+  /** ISO-8601 timestamp of the most recent authenticated request, or `null`. */
+  last_used_at: string | null;
+  /** ISO-8601 timestamp the key was revoked, or `null` if still active. */
+  revoked_at: string | null;
+  /** ISO-8601 expiry, or `null` if non-expiring. */
+  expires_at: string | null;
+}
+
+/**
+ * Response from `rotate()`. Carries the freshly-minted plaintext `api_key` —
+ * the one and ONLY time the SDK will ever expose it. Persist it immediately;
+ * the server cannot return it again.
+ */
+export interface RotatedApiKey {
+  /** Stable identifier of the new key. */
+  id: string;
+  /** Human label (the `name` arg, or `"rotated"` when omitted). */
+  name: string;
+  /** Non-secret prefix safe to display (e.g. `opst_live_AbCd...`). */
+  prefix: string;
+  /** **Plaintext key. Returned ONCE. Persist immediately — it cannot be retrieved later.** */
+  api_key: string;
+  /** ISO-8601 timestamp the key was created. */
+  created_at: string;
+  /** `true` when `revoke_others: true` was honoured and all other active keys were revoked. */
+  revoked_others: boolean;
+}
+
+/** Body for `rotate()`. Both fields are optional; an empty body is valid. */
+export interface RotateApiKeyInput {
+  /** Label for the new key (1-100 chars). Defaults server-side to `"rotated"`. */
+  name?: string;
+  /** When `true`, revoke every OTHER active key in the workspace atomically. */
+  revoke_others?: boolean;
+}
+
+interface ListResponse {
+  data: ApiKey[];
+}
+
+/**
+ * API key resource — list metadata and rotate (create + optionally revoke
+ * others) keys for a given workspace. The Bearer key used by the SDK MUST
+ * already belong to the workspace it's operating on; the server enforces this.
+ */
+export class ApiKeysResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List every API key in a workspace — metadata only. Plaintext and hash are
+   * NEVER included. Useful for displaying key inventories in dashboards or
+   * pruning stale credentials.
+   *
+   * The response is unwrapped: the SDK returns the `ApiKey[]` array directly,
+   * not the `{ data: [...] }` envelope the wire format uses.
+   *
+   * @example
+   * ```bash
+   * curl https://api.outposted.one/v1/workspaces/ws_123/api-keys \
+   *   -H "Authorization: Bearer opst_live_..."
+   * ```
+   *
+   * @example
+   * ```ts
+   * const keys = await client.apiKeys.list('ws_123');
+   * for (const k of keys) {
+   *   console.log(k.prefix, k.last_used_at);
+   * }
+   * ```
+   */
+  async list(workspaceId: string): Promise<ApiKey[]> {
+    const response = await this.http.request<ListResponse>({
+      method: 'GET',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/api-keys`,
+    });
+    return response.data ?? [];
+  }
+
+  /**
+   * Rotate (create) a new API key for a workspace. When `revoke_others: true`,
+   * every other active key in the workspace is revoked atomically in the same
+   * operation — the canonical rotation flow.
+   *
+   * **CRITICAL — read the response carefully:** the returned `api_key` field
+   * is the PLAINTEXT key, and the server returns it exactly ONCE on this call.
+   * The plaintext is never persisted server-side and CANNOT be retrieved
+   * again. Persist `result.api_key` to your secret store IMMEDIATELY — before
+   * any other operation that could throw — or you'll have to rotate again to
+   * recover.
+   *
+   * @example
+   * ```bash
+   * # Simple rotation — keeps existing keys alive.
+   * curl -X POST https://api.outposted.one/v1/workspaces/ws_123/api-keys \
+   *   -H "Authorization: Bearer opst_live_..." \
+   *   -H "Content-Type: application/json" \
+   *   -d '{"name":"ci-pipeline"}'
+   *
+   * # Full rotation — new key + revoke every other active key.
+   * curl -X POST https://api.outposted.one/v1/workspaces/ws_123/api-keys \
+   *   -H "Authorization: Bearer opst_live_..." \
+   *   -H "Content-Type: application/json" \
+   *   -d '{"name":"post-leak","revoke_others":true}'
+   * ```
+   *
+   * @example
+   * ```ts
+   * const result = await client.apiKeys.rotate('ws_123', {
+   *   name: 'post-leak',
+   *   revoke_others: true,
+   * });
+   * // ⚠️ result.api_key is the plaintext — store it NOW.
+   * await secretStore.put('OUTPOSTED_API_KEY', result.api_key);
+   * ```
+   */
+  async rotate(workspaceId: string, input: RotateApiKeyInput = {}): Promise<RotatedApiKey> {
+    return this.http.request<RotatedApiKey>({
+      method: 'POST',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/api-keys`,
+      body: input,
+    });
+  }
+}

package/src/resources/brands.ts

@@ -0,0 +1,127 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/resources/brands — Brand publishing identities.
+//
+// A Brand is a publishing identity inside a workspace. One brand can connect
+// multiple platforms (e.g. 1 IG handle + 1 FB Page + 1 Threads). The slug is
+// unique per workspace.
+//
+// Endpoints proxied here (see apps/api/src/app/api/v1/workspaces/[wsId]/brands):
+//   - GET  /v1/workspaces/:wsId/brands           → list
+//   - POST /v1/workspaces/:wsId/brands           → create
+//   - GET  /v1/workspaces/:wsId/brands/:brandId  → fetch one (with connections)
+//
+// All methods unwrap the API envelope (`{ brand }` / `{ brands }`) so the
+// caller gets the domain entity directly. Errors are surfaced as the typed
+// OutpostedError subclasses produced by the transport layer.
+// ────────────────────────────────────────────────────────────────────────────
+
+import type { Brand, BrandCreateInput } from '@outposted/domain';
+import { OutpostedNotFoundError } from '../errors';
+import type { HttpClient } from '../transport';
+
+/**
+ * Payload accepted by `BrandsResource.create`. Mirrors the POST body the API
+ * expects — `workspace_id` is taken from the URL, so we omit it from the body
+ * shape exposed by the SDK.
+ */
+export type BrandCreateBody = Omit<BrandCreateInput, 'workspace_id'>;
+
+/**
+ * SDK accessor for the `/v1/workspaces/:wsId/brands` collection.
+ *
+ * @example
+ * ```ts
+ * const outposted = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+ * const brands = await outposted.brands.list('ws_123');
+ * ```
+ */
+export class BrandsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List every brand in a workspace, newest first.
+   *
+   * @example curl
+   * ```bash
+   * curl -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   https://api.outposted.one/v1/workspaces/ws_123/brands
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const brands = await outposted.brands.list('ws_123');
+   * console.log(brands.map((b) => b.slug));
+   * ```
+   */
+  async list(workspaceId: string): Promise<Brand[]> {
+    const { brands } = await this.http.request<{ brands: Brand[] }>({
+      method: 'GET',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/brands`,
+    });
+    return brands;
+  }
+
+  /**
+   * Create a brand inside a workspace. Slugs are unique per workspace; a
+   * conflicting slug surfaces as `OutpostedConflictError` (HTTP 409).
+   *
+   * @example curl
+   * ```bash
+   * curl -X POST -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   -H "Content-Type: application/json" \
+   *   -d '{"name":"Coke","slug":"coke","brand_type":"product"}' \
+   *   https://api.outposted.one/v1/workspaces/ws_123/brands
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const brand = await outposted.brands.create('ws_123', {
+   *   name: 'Coke',
+   *   slug: 'coke',
+   *   brand_type: 'product',
+   * });
+   * ```
+   */
+  async create(workspaceId: string, input: BrandCreateBody): Promise<Brand> {
+    const { brand } = await this.http.request<{ brand: Brand }>({
+      method: 'POST',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/brands`,
+      body: input,
+    });
+    return brand;
+  }
+
+  /**
+   * Fetch a single brand by id. The API responds with the brand row plus its
+   * nested `connected_accounts` — the SDK returns the unwrapped object.
+   *
+   * Throws `OutpostedNotFoundError` (HTTP 404) when the brand does not exist
+   * or does not belong to the authenticated workspace.
+   *
+   * @example curl
+   * ```bash
+   * curl -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   https://api.outposted.one/v1/workspaces/ws_123/brands/brand_abc
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const brand = await outposted.brands.get('ws_123', 'brand_abc');
+   * ```
+   */
+  async get(workspaceId: string, brandId: string): Promise<Brand> {
+    const { brand } = await this.http.request<{ brand: Brand | null }>({
+      method: 'GET',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/brands/${encodeURIComponent(brandId)}`,
+    });
+    if (!brand) {
+      // Defense in depth — the API itself returns 404 for missing brands, but
+      // if it ever returns 200 with a null body we still want a typed error.
+      throw new OutpostedNotFoundError(`brand ${brandId} not found in workspace ${workspaceId}`, {
+        status: 404,
+        code: 'brand_not_found',
+      });
+    }
+    return brand;
+  }
+}

package/src/resources/connections.ts

@@ -0,0 +1,115 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/resources/connections — ConnectedAccount resource.
+//
+// A `connected_account` ties a brand to one external account on one platform
+// (e.g. brand `coke` → instagram → ig_user_id 1234). They're created
+// automatically by the OAuth flow: the user is redirected to the platform,
+// authorizes, and the callback handler persists the encrypted token + handle
+// before bouncing back to the app. The SDK exposes the entry point of that
+// flow (`getOAuthStartUrl`) so server-side integrations can mint redirect
+// URLs without going through a UI.
+//
+// `list()` is a stub today — the V0 API surface doesn't include a list
+// endpoint for connected accounts. When one lands (planned route:
+// `GET /api/v1/workspaces/:wsId/brands/:brandId/connections`), wire it up
+// here. Until then, calling `list()` throws so consumers fail loud instead
+// of silently getting an empty array.
+//
+// TODO(api): wire `list()` to `GET /api/v1/workspaces/:wsId/brands/:brandId/connections`
+// once that route exists in `apps/api/src/app/api/v1/workspaces/[wsId]/brands/[brandId]/connections/route.ts`.
+// ────────────────────────────────────────────────────────────────────────────
+
+import type { ConnectedAccount, AccountType } from '@outposted/domain';
+import type { HttpClient } from '../transport';
+
+/** Platforms the OAuth start endpoint accepts. Mirrors `StartSchema.platform` in `connections/start/route.ts`. */
+export type ConnectionPlatform =
+  | 'instagram'
+  | 'facebook'
+  | 'threads'
+  | 'youtube'
+  | 'linkedin';
+
+export interface GetOAuthStartUrlOptions {
+  /**
+   * Optional URL the OAuth callback will redirect the user to after the
+   * connection is persisted. Only honored if it's an absolute URL pointing
+   * to a host the backend trusts; otherwise the backend uses the default
+   * post-connect destination.
+   */
+  returnTo?: string;
+}
+
+export class ConnectionsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List the connected accounts attached to a brand.
+   *
+   * **Not implemented in this API version.** The V0 API exposes the OAuth
+   * start endpoint (see `getOAuthStartUrl`) and the callback handler that
+   * creates rows, but does not yet ship a read endpoint. This method exists
+   * so the resource shape is forward-compatible — calling it today throws.
+   *
+   * Equivalent (future) curl:
+   * ```bash
+   * curl https://api.outposted.one/api/v1/workspaces/$WS_ID/brands/$BRAND_ID/connections \
+   *   -H "Authorization: Bearer $OUTPOSTED_API_KEY"
+   * ```
+   *
+   * Throws `Error('Not implemented in this API version — use the OAuth start URL flow to add connections.')`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async list(workspaceId: string, brandId: string): Promise<ConnectedAccount[]> {
+    throw new Error(
+      'Not implemented in this API version — use the OAuth start URL flow to add connections.',
+    );
+  }
+
+  /**
+   * Build the URL the end user should be redirected to in order to authorize
+   * a connection. Does NOT make an HTTP call — pure URL construction.
+   *
+   * Flow:
+   *   1. Your server redirects the end user to this URL.
+   *   2. They authorize on the platform (Instagram / Facebook / etc.).
+   *   3. The platform redirects to Outposted's OAuth callback, which exchanges
+   *      the code for a token, encrypts it, and persists a `ConnectedAccount`
+   *      row automatically.
+   *   4. The user bounces back to your app (default destination, or the URL
+   *      passed via `returnTo` if the backend trusts it).
+   *
+   * SDK call:
+   * ```ts
+   * const outposted = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+   * const url = outposted.connections.getOAuthStartUrl('ws_123', 'brand_456', 'instagram', {
+   *   returnTo: 'https://app.example.com/settings/connections',
+   * });
+   * // redirect the end user there; they authorize on the platform; the
+   * // OAuth callback creates the ConnectedAccount automatically.
+   * res.redirect(url);
+   * ```
+   *
+   * @param workspaceId Workspace that owns the brand.
+   * @param brandId     Brand the new connection will be attached to.
+   * @param platform    Target platform (`instagram` | `facebook` | `threads` | `youtube` | `linkedin`).
+   * @param opts        Optional flags — currently just `returnTo`.
+   */
+  getOAuthStartUrl(
+    workspaceId: string,
+    brandId: string,
+    platform: ConnectionPlatform,
+    opts?: GetOAuthStartUrlOptions,
+  ): string {
+    const url = new URL(`${this.http.baseUrl}/api/v1/oauth/${platform}/start`);
+    url.searchParams.set('brand_id', brandId);
+    url.searchParams.set('workspace_id', workspaceId);
+    if (opts?.returnTo) {
+      url.searchParams.set('return_to', opts.returnTo);
+    }
+    return url.toString();
+  }
+}
+
+// Re-export the domain types so consumers don't need a second import.
+export type { ConnectedAccount, AccountType };