@outposted/node 0.1.0

package/src/resources/oauth.ts

@@ -0,0 +1,165 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/resources/oauth — OAuth start URL builder.
+//
+// This resource is intentionally **pure**: every method returns a URL string
+// and performs NO HTTP I/O. The customer redirects the end user's browser to
+// the returned URL; the user authorizes on the platform's site; the OAuth
+// callback inside Outposted API (see apps/api/src/app/api/v1/oauth/*/callback)
+// completes the handshake and persists the ConnectedAccount.
+//
+// Shape (per platform):
+//   `${baseUrl}/api/v1/oauth/{platform}/start?brand_id=...&[other params]`
+//
+// Notes:
+//   - `brand_id` is always required — a ConnectedAccount belongs to a brand.
+//   - `workspace_id` is optional. When omitted, the API resolves it from the
+//     authenticated session/API key.
+//   - `return_to` is optional. After a successful callback, Outposted will
+//     redirect the browser to this URL. Caller passes a raw URL string; the
+//     SDK URL-encodes it.
+//   - LinkedIn supports `account_type` (`personal` | `page`) to pre-select the
+//     identity flow on the LinkedIn authorize screen.
+//
+// Why a URL builder and not a `POST /start` wrapper:
+//   The OAuth start endpoints expose GET semantics — the call IS the redirect.
+//   Wrapping them in HTTP would mean fetching the redirect ourselves and
+//   re-emitting it, which doesn't work for browser-driven OAuth flows.
+// ────────────────────────────────────────────────────────────────────────────
+
+import type { HttpClient } from '../transport';
+
+/** Common args shared across every `start*` method. */
+interface OAuthStartArgs {
+  /** Brand the resulting ConnectedAccount will belong to. Required. */
+  brandId: string;
+  /** Workspace scope. Optional — the API resolves it from the API key when omitted. */
+  workspaceId?: string;
+  /** Absolute URL the browser is redirected to after a successful callback. */
+  returnTo?: string;
+}
+
+/** LinkedIn-specific args: pre-select personal vs page identity. */
+export interface OAuthLinkedInStartArgs extends OAuthStartArgs {
+  /**
+   * Pre-select the LinkedIn identity type at the authorize screen.
+   *   - `personal` — connect as the authenticated member.
+   *   - `page`     — connect as a Company Page the member administers.
+   */
+  accountType?: 'personal' | 'page';
+}
+
+/**
+ * Builds OAuth start URLs for every supported platform.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { Outposted } from '@outposted/node';
+ *
+ * const outposted = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+ * const app = express();
+ *
+ * app.get('/connect/instagram', (req, res) => {
+ *   const url = outposted.oauth.startInstagram({ brandId: 'brand_abc' });
+ *   res.redirect(url);
+ * });
+ * ```
+ */
+export class OAuthResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Build the Instagram OAuth start URL.
+   *
+   * @example
+   * ```ts
+   * const url = client.oauth.startInstagram({ brandId: 'brand_abc' });
+   * res.redirect(url);
+   * ```
+   */
+  startInstagram(args: OAuthStartArgs): string {
+    return this.build('instagram', args);
+  }
+
+  /**
+   * Build the Facebook OAuth start URL.
+   *
+   * @example
+   * ```ts
+   * const url = client.oauth.startFacebook({
+   *   brandId: 'brand_abc',
+   *   returnTo: 'https://app.example.com/connected',
+   * });
+   * res.redirect(url);
+   * ```
+   */
+  startFacebook(args: OAuthStartArgs): string {
+    return this.build('facebook', args);
+  }
+
+  /**
+   * Build the Threads OAuth start URL.
+   *
+   * @example
+   * ```ts
+   * const url = client.oauth.startThreads({ brandId: 'brand_abc' });
+   * res.redirect(url);
+   * ```
+   */
+  startThreads(args: OAuthStartArgs): string {
+    return this.build('threads', args);
+  }
+
+  /**
+   * Build the YouTube OAuth start URL.
+   *
+   * @example
+   * ```ts
+   * const url = client.oauth.startYouTube({ brandId: 'brand_abc' });
+   * res.redirect(url);
+   * ```
+   */
+  startYouTube(args: OAuthStartArgs): string {
+    return this.build('youtube', args);
+  }
+
+  /**
+   * Build the LinkedIn OAuth start URL. Pass `accountType` to pre-select the
+   * personal vs page authorize flow.
+   *
+   * @example
+   * ```ts
+   * const url = client.oauth.startLinkedIn({
+   *   brandId: 'brand_abc',
+   *   accountType: 'page',
+   * });
+   * res.redirect(url);
+   * ```
+   */
+  startLinkedIn(args: OAuthLinkedInStartArgs): string {
+    const url = new URL(`${this.http.baseUrl}/api/v1/oauth/linkedin/start`);
+    appendCommon(url, args);
+    if (args.accountType !== undefined) {
+      url.searchParams.set('account_type', args.accountType);
+    }
+    return url.toString();
+  }
+
+  // ── internal ─────────────────────────────────────────────────────────────
+
+  private build(platform: 'instagram' | 'facebook' | 'threads' | 'youtube', args: OAuthStartArgs): string {
+    const url = new URL(`${this.http.baseUrl}/api/v1/oauth/${platform}/start`);
+    appendCommon(url, args);
+    return url.toString();
+  }
+}
+
+function appendCommon(url: URL, args: OAuthStartArgs): void {
+  url.searchParams.set('brand_id', args.brandId);
+  if (args.workspaceId !== undefined) {
+    url.searchParams.set('workspace_id', args.workspaceId);
+  }
+  if (args.returnTo !== undefined) {
+    url.searchParams.set('return_to', args.returnTo);
+  }
+}

package/src/resources/webhooks.ts

@@ -0,0 +1,301 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/resources/webhooks — outbound webhook endpoints (E2).
+//
+// A webhook endpoint is a HTTPS URL registered against a workspace that
+// receives signed POSTs when domain events fire (content.published,
+// content.failed, …). The workspace's `whsec_*` secret is generated server-side
+// at create-time and returned ONCE in the response body — losing it means
+// rotating to a new endpoint. The DB only stores the ciphertext.
+//
+// Endpoints proxied here (see apps/api/src/app/api/v1/workspaces/[wsId]/webhooks):
+//   - POST   /v1/workspaces/:wsId/webhooks            → register endpoint
+//   - GET    /v1/workspaces/:wsId/webhooks            → list endpoints
+//   - GET    /v1/workspaces/:wsId/webhooks/:id        → fetch one
+//   - PATCH  /v1/workspaces/:wsId/webhooks/:id        → toggle/update
+//   - DELETE /v1/workspaces/:wsId/webhooks/:id        → hard delete
+//
+// `verify()` delegates straight to `@outposted/webhooks/verifyPayload` — it's
+// the same code path the API + worker use to sign on the way out, so customers
+// can reuse it for inbound verification without installing a second package.
+// ────────────────────────────────────────────────────────────────────────────
+
+import { verifyPayload, type VerifyResult } from '@outposted/webhooks';
+import type { HttpClient } from '../transport';
+
+export type { VerifyResult };
+
+/**
+ * Payload accepted by `WebhooksResource.create`. Only `url` is required —
+ * `description` is a free-form label and `enabled_events` is the subscription
+ * filter (omit/null = receive every event type).
+ */
+export interface CreateWebhookInput {
+  /** Absolute HTTPS URL the worker should POST to (HTTP allowed in dev only). */
+  url: string;
+  /** Optional human-readable label (max 200 chars). */
+  description?: string | null;
+  /**
+   * Event types the endpoint subscribes to (e.g. `['content.published']`).
+   * Omit or pass null to receive every event type the workspace emits.
+   */
+  enabled_events?: string[] | null;
+}
+
+/**
+ * Webhook endpoint as returned by list/get/update. Does NOT contain the
+ * plaintext secret — the API never returns it after creation.
+ */
+export interface Webhook {
+  id: string;
+  workspace_id: string;
+  url: string;
+  description: string | null;
+  enabled_events: string[] | null;
+  active: boolean;
+  last_delivery_at?: string | null;
+  last_delivery_status?: string | null;
+  created_at: string;
+}
+
+/**
+ * Response from `WebhooksResource.create`. Identical to `Webhook` but with the
+ * plaintext `secret` field populated — capture it immediately, it will never
+ * appear in any other response.
+ */
+export interface CreatedWebhook extends Webhook {
+  /**
+   * Plaintext signing secret in `whsec_...` shape. Shown exactly ONCE at
+   * creation — the API stores only the encrypted form. Save it to your secret
+   * manager before discarding the response object.
+   */
+  secret: string;
+}
+
+/**
+ * Patch body accepted by `WebhooksResource.update`. Every field is optional;
+ * at least one must be provided or the API responds 400.
+ */
+export interface UpdateWebhookInput {
+  url?: string;
+  description?: string | null;
+  enabled_events?: string[] | null;
+  active?: boolean;
+}
+
+/**
+ * Options for `WebhooksResource.verify`. Forwarded straight to
+ * `verifyPayload` from `@outposted/webhooks`.
+ */
+export interface VerifyOptions {
+  /** Replay window in seconds (default 300 = 5 min, Stripe-compatible). */
+  toleranceSeconds?: number;
+}
+
+/**
+ * SDK accessor for the `/v1/workspaces/:wsId/webhooks` collection.
+ *
+ * @example
+ * ```ts
+ * const outposted = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+ * const endpoint = await outposted.webhooks.create('ws_123', {
+ *   url: 'https://api.example.com/outposted-webhook',
+ *   enabled_events: ['content.published', 'content.failed'],
+ * });
+ * console.log(endpoint.secret); // 'whsec_...' — store this NOW
+ * ```
+ */
+export class WebhooksResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Register a webhook endpoint inside a workspace. The API generates a fresh
+   * `whsec_*` secret server-side and returns it in the response body —
+   * **this is the only time the plaintext appears**, so capture it before
+   * discarding the response. Subsequent list/get calls never expose it.
+   *
+   * Throws `OutpostedValidationError` (400) on bad URL or unknown event types,
+   * and `OutpostedConflictError` (409) once the workspace hits the 25-endpoint
+   * cap.
+   *
+   * @example curl
+   * ```bash
+   * curl -X POST -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   -H "Content-Type: application/json" \
+   *   -d '{"url":"https://example.com/hook","enabled_events":["content.published"]}' \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/webhooks
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const endpoint = await outposted.webhooks.create('ws_123', {
+   *   url: 'https://example.com/hook',
+   *   enabled_events: ['content.published'],
+   * });
+   * await secretManager.store('OUTPOSTED_WHSEC', endpoint.secret); // ONLY chance
+   * ```
+   */
+  async create(workspaceId: string, input: CreateWebhookInput): Promise<CreatedWebhook> {
+    return this.http.request<CreatedWebhook>({
+      method: 'POST',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/webhooks`,
+      body: input,
+    });
+  }
+
+  /**
+   * List every webhook endpoint registered against the workspace. The plaintext
+   * secret is NEVER included — it only exists in the `create` response.
+   *
+   * @example curl
+   * ```bash
+   * curl -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/webhooks
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const endpoints = await outposted.webhooks.list('ws_123');
+   * for (const ep of endpoints) {
+   *   console.log(ep.url, ep.active);
+   * }
+   * ```
+   */
+  async list(workspaceId: string): Promise<Webhook[]> {
+    const { data } = await this.http.request<{ data: Webhook[] }>({
+      method: 'GET',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/webhooks`,
+    });
+    return data;
+  }
+
+  /**
+   * Fetch a single webhook endpoint by id. Throws `OutpostedNotFoundError`
+   * (404) when the endpoint doesn't exist or belongs to a different workspace.
+   *
+   * @example curl
+   * ```bash
+   * curl -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/webhooks/whep_abc
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * const endpoint = await outposted.webhooks.get('ws_123', 'whep_abc');
+   * ```
+   */
+  async get(workspaceId: string, webhookId: string): Promise<Webhook> {
+    return this.http.request<Webhook>({
+      method: 'GET',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/webhooks/${encodeURIComponent(webhookId)}`,
+    });
+  }
+
+  /**
+   * Patch an existing endpoint. At least one field must be present in `patch`
+   * — sending an empty object responds 400. Toggling `active: false` pauses
+   * deliveries without losing the endpoint row.
+   *
+   * @example curl
+   * ```bash
+   * curl -X PATCH -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   -H "Content-Type: application/json" \
+   *   -d '{"active":false}' \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/webhooks/whep_abc
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * await outposted.webhooks.update('ws_123', 'whep_abc', { active: false });
+   * ```
+   */
+  async update(workspaceId: string, webhookId: string, patch: UpdateWebhookInput): Promise<Webhook> {
+    return this.http.request<Webhook>({
+      method: 'PATCH',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/webhooks/${encodeURIComponent(webhookId)}`,
+      body: patch,
+    });
+  }
+
+  /**
+   * Hard-delete an endpoint. Idempotent from the caller's perspective —
+   * deleting an already-gone endpoint responds 404 (surfaced as
+   * `OutpostedNotFoundError`).
+   *
+   * @example curl
+   * ```bash
+   * curl -X DELETE -H "Authorization: Bearer $OUTPOSTED_API_KEY" \
+   *   https://api.outposted.one/api/v1/workspaces/ws_123/webhooks/whep_abc
+   * ```
+   *
+   * @example SDK
+   * ```ts
+   * await outposted.webhooks.delete('ws_123', 'whep_abc');
+   * ```
+   */
+  async delete(workspaceId: string, webhookId: string): Promise<void> {
+    await this.http.request<undefined>({
+      method: 'DELETE',
+      path: `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/webhooks/${encodeURIComponent(webhookId)}`,
+    });
+  }
+
+  /**
+   * Verify an inbound signed delivery using the workspace's `whsec_*` secret
+   * (the one returned ONCE by `create`). Delegates to
+   * `verifyPayload` from `@outposted/webhooks` so the verification code is
+   * byte-identical to the API + worker signing path.
+   *
+   * Returns a discriminated union — branch on `result.ok` and `result.code` to
+   * respond with the right HTTP status:
+   *   - `ok: true`                              → 200 OK, process the event
+   *   - `code: 'missing' | 'malformed'`         → 400 Bad Request
+   *   - `code: 'unsupported_version'`           → 400 Bad Request
+   *   - `code: 'timestamp_out_of_tolerance'`    → 408 Request Timeout
+   *   - `code: 'signature_mismatch'`            → 401 Unauthorized
+   *
+   * `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.
+   *
+   * @example Express middleware
+   * ```ts
+   * import express from 'express';
+   * import { Outposted } from '@outposted/node';
+   *
+   * const outposted = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+   * const secret = process.env.OUTPOSTED_WHSEC!; // saved from webhooks.create()
+   *
+   * const app = express();
+   *
+   * // raw body capture — this MUST come before any JSON middleware
+   * 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 = outposted.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);
+   *     // … process event …
+   *     res.status(200).end();
+   *   },
+   * );
+   * ```
+   */
+  verify(
+    rawBody: string,
+    headerValue: string | null | undefined,
+    secret: string,
+    options: VerifyOptions = {},
+  ): VerifyResult {
+    return verifyPayload(rawBody, headerValue, secret, options);
+  }
+}

package/src/resources/workspaces.ts

@@ -0,0 +1,70 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/resources/workspaces — Workspace resource.
+//
+// Wraps `GET /api/v1/workspaces/me`: returns the workspace tied to the
+// authenticated API key. This is the canonical "who am I?" probe — handy as
+// a startup health check that the SDK is configured with a valid key.
+//
+// The API envelope is `{ workspace, api_key_id, rate_limit }`; this resource
+// unwraps it so callers get a clean `Workspace` object. The other envelope
+// fields (api_key_id, rate_limit) are reachable via the standard rate-limit
+// headers and are not surfaced here to keep the resource minimal.
+// ────────────────────────────────────────────────────────────────────────────
+
+import type { HttpClient } from '../transport';
+
+/**
+ * Workspace tied to an API key. Shape mirrors the columns returned by
+ * `GET /api/v1/workspaces/me`.
+ */
+export interface Workspace {
+  id: string;
+  slug: string;
+  name: string;
+  stripe_customer_id: string | null;
+  currency: string;
+  created_at: string;
+  trial_ends_at: string | null;
+}
+
+interface WorkspaceMeResponse {
+  workspace: Workspace;
+  api_key_id: string;
+  rate_limit: {
+    limit: number;
+    remaining: number;
+    reset_at: string;
+  };
+}
+
+export class WorkspacesResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Fetch the workspace bound to the current API key.
+   *
+   * Equivalent curl:
+   * ```bash
+   * curl https://api.outposted.one/api/v1/workspaces/me \
+   *   -H "Authorization: Bearer $OUTPOSTED_API_KEY"
+   * ```
+   *
+   * SDK call:
+   * ```ts
+   * const outposted = new Outposted({ apiKey: process.env.OUTPOSTED_API_KEY! });
+   * const workspace = await outposted.workspaces.me();
+   * console.log(workspace.slug); // "acme"
+   * ```
+   *
+   * Throws `OutpostedAuthError` (401) if the key is invalid, or
+   * `OutpostedNotFoundError` (404) if the workspace row was deleted while the
+   * key still exists.
+   */
+  async me(): Promise<Workspace> {
+    const response = await this.http.request<WorkspaceMeResponse>({
+      method: 'GET',
+      path: '/api/v1/workspaces/me',
+    });
+    return response.workspace;
+  }
+}