@outposted/node 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 — 2026-06-03
+
+- Initial release
+- Resources: workspaces, brands, apiKeys, contents, connections, webhooks, deliveries, oauth
+- HMAC-SHA256 signed webhook verification (Stripe-style)
+- Automatic retry on 5xx and network errors
+- TypeScript types throughout

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RC Negocios Digitais Ltda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,294 @@
+# @outposted/node
+
+Outposted Node.js client. Publish content to Instagram, Facebook, YouTube, LinkedIn, Threads from a single API call. Resilient HMAC-SHA256 signed webhooks with built-in verification.
+
+## Installation
+
+```bash
+pnpm add @outposted/node
+# or
+npm install @outposted/node
+# or
+yarn add @outposted/node
+```
+
+Requires Node.js >= 18 (uses native `fetch` and `node:crypto`).
+
+## Quick start
+
+```ts
+import { Outposted } from '@outposted/node';
+
+const client = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+
+// Publish an Instagram image post
+const result = await client.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)`);
+}
+```
+
+The client validates the `opst_` prefix at construction. Resources are instantiated lazily — first property access builds the resource class, subsequent accesses return the cached instance.
+
+### Options
+
+```ts
+new Outposted({
+  apiKey: 'opst_live_...', // required, must start with opst_
+  baseUrl: 'https://api.outposted.one', // optional override
+  fetch: customFetch, // optional fetch polyfill / interceptor
+});
+```
+
+The transport layer retries transient failures (5xx + network errors) up to 3 attempts with exponential backoff (250ms, 500ms, 1000ms). 4xx errors are never retried — they surface as typed errors immediately.
+
+## Resources
+
+### `workspaces`
+
+The "who am I?" probe for the authenticated API key.
+
+```ts
+const workspace = await client.workspaces.me();
+console.log(workspace.id, workspace.slug);
+```
+
+### `brands`
+
+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).
+
+```ts
+const brands = await client.brands.list('ws_123');
+const brand = await client.brands.get('ws_123', 'brand_abc');
+const fresh = await client.brands.create('ws_123', {
+  name: 'Coke',
+  slug: 'coke',
+  brand_type: 'product',
+});
+```
+
+### `contents`
+
+The core publishing surface. Create, list, fetch, cancel, and retry contents.
+
+```ts
+// Create + dispatch
+await client.contents.create('ws_123', {
+  brand_id: 'brand_abc',
+  content_type: 'post',
+  target_platforms: ['instagram'],
+  content: { caption: '…', media: [{ type: 'image', url: '…' }] },
+});
+
+// Multi-connection disambiguation (brand has ≥2 LinkedIn connections)
+await client.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 surfaces' },
+});
+
+const { items, total } = await client.contents.list('ws_123', { status: 'published', limit: 20 });
+const detail = await client.contents.get('ws_123', 'cnt_abc');
+await client.contents.cancel('ws_123', 'cnt_abc');
+await client.contents.retry('ws_123', 'cnt_abc');
+```
+
+### `connections`
+
+Build OAuth start URLs that the end user is redirected to in order to authorize a platform connection. The callback handler inside Outposted creates the `ConnectedAccount` row automatically.
+
+```ts
+const url = client.connections.getOAuthStartUrl('ws_123', 'brand_abc', 'instagram', {
+  returnTo: 'https://app.example.com/settings/connections',
+});
+res.redirect(url);
+```
+
+`list(workspaceId, brandId)` exists but throws today — the V0 API does not yet expose a list endpoint for connected accounts. Use `client.brands.get(...)` and inspect `brand.connected_accounts` in the meantime.
+
+### `webhooks`
+
+Register, list, update, delete webhook endpoints. **Capture `result.secret` immediately on create — the plaintext is shown only once.**
+
+```ts
+const endpoint = await client.webhooks.create('ws_123', {
+  url: 'https://api.example.com/outposted-webhook',
+  enabled_events: ['content.published', 'content.failed'],
+});
+await secretManager.store('OUTPOSTED_WHSEC', endpoint.secret); // whsec_..., shown ONCE
+
+const endpoints = await client.webhooks.list('ws_123');
+await client.webhooks.update('ws_123', endpoint.id, { active: false });
+await client.webhooks.delete('ws_123', endpoint.id);
+```
+
+`webhooks.verify(rawBody, header, secret)` is the inbound verifier — see the dedicated section below.
+
+### `deliveries`
+
+Inspect webhook delivery history and manually retry stuck deliveries.
+
+```ts
+const page = await client.deliveries.list('ws_123', 'wh_456', {
+  status: 'failed',
+  since: '2026-06-01T00:00:00.000Z',
+  limit: 50,
+});
+for (const delivery of page.items) {
+  console.log(delivery.id, delivery.last_response_status);
+}
+
+await client.deliveries.redeliver('ws_123', 'del_789');
+```
+
+### `oauth`
+
+Pure URL builders — no HTTP I/O. The customer redirects the end user's browser to the returned URL; the platform handshake completes server-side and persists the `ConnectedAccount`.
+
+```ts
+const ig = client.oauth.startInstagram({ brandId: 'brand_abc' });
+const fb = client.oauth.startFacebook({
+  brandId: 'brand_abc',
+  returnTo: 'https://app.example.com/connected',
+});
+const yt = client.oauth.startYouTube({ brandId: 'brand_abc' });
+const th = client.oauth.startThreads({ brandId: 'brand_abc' });
+const li = client.oauth.startLinkedIn({ brandId: 'brand_abc', accountType: 'page' });
+
+res.redirect(ig);
+```
+
+### `apiKeys`
+
+List API key metadata and rotate (create + optionally revoke others). The plaintext key is returned exactly once on `rotate()`.
+
+```ts
+const keys = await client.apiKeys.list('ws_123');
+
+// Full rotation hygiene: create a fresh key + revoke every other active key atomically
+const result = await client.apiKeys.rotate('ws_123', {
+  name: 'post-leak',
+  revoke_others: true,
+});
+await secretStore.put('OUTPOSTED_API_KEY', result.api_key); // plaintext, shown ONCE
+```
+
+## Webhook verification
+
+The SDK ships `webhooks.verify()` so consumers don't need a second package. It's byte-identical to the signing path used by the API + worker.
+
+`rawBody` MUST be the exact bytes of the request body — any reformatting (key re-ordering, whitespace normalization) breaks the HMAC. Capture the raw stream BEFORE any JSON parser touches it.
+
+```ts
+import express from 'express';
+import { Outposted } from '@outposted/node';
+
+const client = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+const secret = process.env.OUTPOSTED_WHSEC!; // saved from webhooks.create()
+
+const app = express();
+
+app.post('/outposted-webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const rawBody = req.body.toString('utf8');
+  const sig = req.header('x-outposted-signature');
+  const result = client.webhooks.verify(rawBody, sig, secret);
+
+  if (!result.ok) {
+    const status =
+      result.code === 'signature_mismatch'
+        ? 401
+        : result.code === 'timestamp_out_of_tolerance'
+          ? 408
+          : 400;
+    return res.status(status).json({ error: result.code, detail: result.detail });
+  }
+
+  const event = JSON.parse(rawBody);
+  // … react to event.type, event.data …
+  res.status(200).end();
+});
+```
+
+`verify()` returns a discriminated union:
+
+```ts
+type VerifyResult =
+  | { ok: true; timestamp: number }
+  | { ok: false; code: 'missing'; detail: string }
+  | { ok: false; code: 'malformed'; detail: string }
+  | { ok: false; code: 'unsupported_version'; detail: string }
+  | { ok: false; code: 'timestamp_out_of_tolerance'; detail: string }
+  | { ok: false; code: 'signature_mismatch'; detail: string };
+```
+
+| `code`                       | HTTP suggestion |
+| ---------------------------- | --------------- |
+| `ok: true`                   | 200 OK          |
+| `missing` / `malformed`      | 400             |
+| `unsupported_version`        | 400             |
+| `timestamp_out_of_tolerance` | 408             |
+| `signature_mismatch`         | 401             |
+
+Default replay tolerance is 300s (Stripe-compatible). Override with `client.webhooks.verify(body, sig, secret, { toleranceSeconds: 600 })`.
+
+## Errors
+
+Every HTTP error surfaces as a typed `OutpostedError` subclass. Branch with `instanceof`.
+
+| Class                      | Fires on                                                        |
+| -------------------------- | --------------------------------------------------------------- |
+| `OutpostedAuthError`       | 401 — API key missing, invalid, or revoked.                     |
+| `OutpostedForbiddenError`  | 403 — key is valid but lacks permission for the resource.       |
+| `OutpostedNotFoundError`   | 404 — resource does not exist or belongs to another tenant.     |
+| `OutpostedConflictError`   | 409 — slug clash, idempotency replay, `cancel_too_late`, etc.   |
+| `OutpostedValidationError` | 400 / 422 — payload shape invalid; carries `issues[]`.          |
+| `OutpostedRateLimitError`  | 429 — carries `retryAfter` (seconds) parsed from `Retry-After`. |
+| `OutpostedServerError`     | 5xx — automatically retried 2× before surfacing.                |
+| `OutpostedNetworkError`    | DNS failure, connection refused, abort, timeout — no response.  |
+| `OutpostedError`           | Base class — catches any of the above.                          |
+
+```ts
+import {
+  Outposted,
+  OutpostedAuthError,
+  OutpostedRateLimitError,
+  OutpostedValidationError,
+} from '@outposted/node';
+
+try {
+  await client.contents.create('ws_123', input);
+} catch (err) {
+  if (err instanceof OutpostedAuthError) {
+    // rotate the key
+  } else if (err instanceof OutpostedRateLimitError) {
+    console.log(`rate limited — retry in ${err.retryAfter}s`);
+  } else if (err instanceof OutpostedValidationError) {
+    for (const issue of err.issues) {
+      console.error(issue.path, issue.message);
+    }
+  } else {
+    throw err;
+  }
+}
+```
+
+Every error carries `status`, `code`, `requestId` (X-Outposted-Request-ID, for support correlation), `body`, and `headers`.
+
+## License
+
+MIT
+
+## Reference
+
+Full API docs: <https://docs.outposted.one>

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@outposted/node",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Outposted Node.js client — publish to Instagram, Facebook, YouTube, LinkedIn, Threads from one API call.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "outposted",
+    "social-media",
+    "instagram",
+    "facebook",
+    "youtube",
+    "linkedin",
+    "threads",
+    "webhooks",
+    "api",
+    "sdk",
+    "publishing"
+  ],
+  "homepage": "https://docs.outposted.one",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Studio-1103/outposted.git",
+    "directory": "packages/sdk-node"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src __tests__ --max-warnings 0"
+  },
+  "dependencies": {
+    "@outposted/domain": "workspace:*",
+    "@outposted/webhooks": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5",
+    "vitest": "^2",
+    "eslint": "^9",
+    "typescript-eslint": "^8",
+    "@eslint/js": "^9"
+  }
+}

package/src/client.ts

@@ -0,0 +1,91 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/client — Stripe-style multi-resource client.
+//
+//   import { Outposted } from '@outposted/node';
+//   const client = new Outposted({ apiKey: 'opst_live_...' });
+//   await client.contents.create(workspaceId, { ... });
+//
+// API key prefix is validated at construction (opst_*). Resources are
+// instantiated lazily — the first property access builds the resource class,
+// subsequent accesses return the cached instance. This keeps cold start cheap
+// for callers that touch only one resource.
+// ────────────────────────────────────────────────────────────────────────────
+
+import { HttpClient, type FetchLike } from './transport';
+import { ApiKeysResource } from './resources/api-keys';
+import { BrandsResource } from './resources/brands';
+import { ConnectionsResource } from './resources/connections';
+import { ContentsResource } from './resources/contents';
+import { DeliveriesResource } from './resources/deliveries';
+import { OAuthResource } from './resources/oauth';
+import { WebhooksResource } from './resources/webhooks';
+import { WorkspacesResource } from './resources/workspaces';
+
+export interface OutpostedOptions {
+  apiKey: string;
+  baseUrl?: string;
+  fetch?: FetchLike;
+}
+
+const API_KEY_PREFIX = 'opst_';
+
+export class Outposted {
+  private readonly http: HttpClient;
+
+  private _workspaces?: WorkspacesResource;
+  private _brands?: BrandsResource;
+  private _apiKeys?: ApiKeysResource;
+  private _contents?: ContentsResource;
+  private _connections?: ConnectionsResource;
+  private _webhooks?: WebhooksResource;
+  private _deliveries?: DeliveriesResource;
+  private _oauth?: OAuthResource;
+
+  constructor(options: OutpostedOptions) {
+    if (!options || typeof options.apiKey !== 'string' || options.apiKey.trim() === '') {
+      throw new Error('Outposted: apiKey is required.');
+    }
+    if (!options.apiKey.startsWith(API_KEY_PREFIX)) {
+      throw new Error(
+        `Outposted: apiKey must start with "${API_KEY_PREFIX}" (got "${options.apiKey.slice(0, 8)}...").`,
+      );
+    }
+    this.http = new HttpClient({
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      fetch: options.fetch,
+    });
+  }
+
+  get workspaces(): WorkspacesResource {
+    return (this._workspaces ??= new WorkspacesResource(this.http));
+  }
+
+  get brands(): BrandsResource {
+    return (this._brands ??= new BrandsResource(this.http));
+  }
+
+  get apiKeys(): ApiKeysResource {
+    return (this._apiKeys ??= new ApiKeysResource(this.http));
+  }
+
+  get contents(): ContentsResource {
+    return (this._contents ??= new ContentsResource(this.http));
+  }
+
+  get connections(): ConnectionsResource {
+    return (this._connections ??= new ConnectionsResource(this.http));
+  }
+
+  get webhooks(): WebhooksResource {
+    return (this._webhooks ??= new WebhooksResource(this.http));
+  }
+
+  get deliveries(): DeliveriesResource {
+    return (this._deliveries ??= new DeliveriesResource(this.http));
+  }
+
+  get oauth(): OAuthResource {
+    return (this._oauth ??= new OAuthResource(this.http));
+  }
+}

package/src/errors.ts

@@ -0,0 +1,214 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/errors — error hierarchy for SDK consumers.
+//
+// Shape mirrors Stripe SDK: one base class (OutpostedError) with discriminated
+// subclasses per HTTP semantic. Consumers `instanceof` to branch.
+//
+// Static factory `OutpostedError.fromResponse(status, body, headers, requestId)`
+// is the canonical mapping point from raw HTTP responses to the right subclass.
+// Transport calls it on any 4xx/5xx; consumers don't.
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface OutpostedErrorBody {
+  error?: {
+    code?: string;
+    message?: string;
+    issues?: unknown;
+  };
+  message?: string;
+  code?: string;
+  issues?: unknown;
+}
+
+export interface OutpostedErrorOptions {
+  status?: number;
+  code?: string;
+  requestId?: string;
+  body?: OutpostedErrorBody | null;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Base class for every error thrown by the Outposted SDK. Carries the HTTP
+ * status (when there was a response), our internal error code, the parsed
+ * body, and the X-Outposted-Request-ID header for support correlation.
+ */
+export class OutpostedError extends Error {
+  public readonly status?: number;
+  public readonly code?: string;
+  public readonly requestId?: string;
+  public readonly body?: OutpostedErrorBody | null;
+  public readonly headers?: Record<string, string>;
+
+  constructor(message: string, options: OutpostedErrorOptions = {}) {
+    super(message);
+    this.name = 'OutpostedError';
+    this.status = options.status;
+    this.code = options.code;
+    this.requestId = options.requestId;
+    this.body = options.body ?? null;
+    this.headers = options.headers;
+  }
+
+  /**
+   * Map an HTTP response onto the most specific OutpostedError subclass.
+   * Called by the transport layer on every non-2xx response.
+   */
+  static fromResponse(
+    status: number,
+    body: OutpostedErrorBody | null,
+    headers: Record<string, string>,
+    requestId: string | undefined,
+  ): OutpostedError {
+    const message = extractMessage(body) ?? `Outposted API error (HTTP ${status})`;
+    const code = extractCode(body);
+    const base = { status, code, requestId, body, headers };
+
+    if (status === 401) {
+      return new OutpostedAuthError(message, base);
+    }
+    if (status === 403) {
+      return new OutpostedForbiddenError(message, base);
+    }
+    if (status === 404) {
+      return new OutpostedNotFoundError(message, base);
+    }
+    if (status === 409) {
+      return new OutpostedConflictError(message, base);
+    }
+    if (status === 422 || status === 400) {
+      const issues = extractIssues(body);
+      return new OutpostedValidationError(message, { ...base, issues });
+    }
+    if (status === 429) {
+      const retryAfter = parseRetryAfter(headers);
+      return new OutpostedRateLimitError(message, { ...base, retryAfter });
+    }
+    if (status >= 500) {
+      return new OutpostedServerError(message, base);
+    }
+    return new OutpostedError(message, base);
+  }
+}
+
+export class OutpostedAuthError extends OutpostedError {
+  constructor(message: string, options: OutpostedErrorOptions = {}) {
+    super(message, options);
+    this.name = 'OutpostedAuthError';
+  }
+}
+
+export class OutpostedForbiddenError extends OutpostedError {
+  constructor(message: string, options: OutpostedErrorOptions = {}) {
+    super(message, options);
+    this.name = 'OutpostedForbiddenError';
+  }
+}
+
+export class OutpostedNotFoundError extends OutpostedError {
+  constructor(message: string, options: OutpostedErrorOptions = {}) {
+    super(message, options);
+    this.name = 'OutpostedNotFoundError';
+  }
+}
+
+export class OutpostedConflictError extends OutpostedError {
+  constructor(message: string, options: OutpostedErrorOptions = {}) {
+    super(message, options);
+    this.name = 'OutpostedConflictError';
+  }
+}
+
+export interface ValidationIssue {
+  path?: (string | number)[];
+  message?: string;
+  code?: string;
+  [k: string]: unknown;
+}
+
+export interface OutpostedValidationErrorOptions extends OutpostedErrorOptions {
+  issues?: ValidationIssue[];
+}
+
+export class OutpostedValidationError extends OutpostedError {
+  public readonly issues: ValidationIssue[];
+
+  constructor(message: string, options: OutpostedValidationErrorOptions = {}) {
+    super(message, options);
+    this.name = 'OutpostedValidationError';
+    this.issues = options.issues ?? [];
+  }
+}
+
+export interface OutpostedRateLimitErrorOptions extends OutpostedErrorOptions {
+  retryAfter?: number;
+}
+
+export class OutpostedRateLimitError extends OutpostedError {
+  /** Seconds to wait before retrying, parsed from Retry-After header. */
+  public readonly retryAfter?: number;
+
+  constructor(message: string, options: OutpostedRateLimitErrorOptions = {}) {
+    super(message, options);
+    this.name = 'OutpostedRateLimitError';
+    this.retryAfter = options.retryAfter;
+  }
+}
+
+export class OutpostedServerError extends OutpostedError {
+  constructor(message: string, options: OutpostedErrorOptions = {}) {
+    super(message, options);
+    this.name = 'OutpostedServerError';
+  }
+}
+
+/**
+ * Thrown when the request never produced an HTTP response — DNS failure,
+ * connection refused, fetch timeout, abort, etc. No status, no body.
+ */
+export class OutpostedNetworkError extends OutpostedError {
+  public readonly cause?: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = 'OutpostedNetworkError';
+    this.cause = cause;
+  }
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function extractMessage(body: OutpostedErrorBody | null): string | undefined {
+  if (!body) return undefined;
+  if (body.error?.message) return body.error.message;
+  if (body.message) return body.message;
+  return undefined;
+}
+
+function extractCode(body: OutpostedErrorBody | null): string | undefined {
+  if (!body) return undefined;
+  if (body.error?.code) return body.error.code;
+  if (body.code) return body.code;
+  return undefined;
+}
+
+function extractIssues(body: OutpostedErrorBody | null): ValidationIssue[] {
+  if (!body) return [];
+  const raw = body.error?.issues ?? body.issues;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((x): x is ValidationIssue => typeof x === 'object' && x !== null);
+}
+
+function parseRetryAfter(headers: Record<string, string>): number | undefined {
+  const raw = headers['retry-after'];
+  if (!raw) return undefined;
+  const asInt = Number(raw);
+  if (Number.isFinite(asInt) && asInt >= 0) return asInt;
+  // RFC 7231 also allows HTTP-date — convert to seconds-from-now.
+  const asDate = Date.parse(raw);
+  if (Number.isFinite(asDate)) {
+    const delta = Math.ceil((asDate - Date.now()) / 1000);
+    return delta > 0 ? delta : 0;
+  }
+  return undefined;
+}