@medalsocial/sdk 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medalsocial/sdk",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "TypeScript SDK for Medal Social API — posts, emails, contacts, deals, and GDPR compliance",
   "license": "Apache-2.0",
   "author": "Medal Social / Ali Aljumaili",
@@ -50,7 +50,11 @@
   },
   "files": [
     "dist",
-    "openapi"
+    "openapi",
+    "skills",
+    "!skills/_artifacts",
+    "!skills/**/_artifacts",
+    "!skills/**/_artifacts/**"
   ],
   "keywords": [
     "medal",
@@ -65,7 +69,8 @@
     "contacts",
     "deals",
     "posts",
-    "social-media"
+    "social-media",
+    "tanstack-intent"
   ],
   "dependencies": {
     "zod": "^3.23.8"
@@ -78,6 +83,7 @@
     "@commitlint/config-conventional": "^19.4.0",
     "@redocly/cli": "^2.31.4",
     "@secretlint/secretlint-rule-preset-recommend": "^9.3.2",
+    "@tanstack/intent": "0.0.41",
     "@types/node": "^24.3.2",
     "@vitest/coverage-v8": "^2.0.5",
     "husky": "^9.1.6",

package/skills/client/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: client
+description: Use when instantiating the `Medal` class from `@medalsocial/sdk`, configuring auth (API key vs OAuth), setting `baseUrl`, debugging an HTTP response or `MedalApiError`, reasoning about retry behavior, or running the SDK in a browser / edge runtime. Required reading before any code that calls into the SDK at the client level.
+---
+
+# Medal Social SDK — Client
+
+## When to load this skill
+
+- Instantiating `new Medal(...)`.
+- Choosing between an API key and an OAuth access token.
+- Configuring `baseUrl`, `timeout`, or `workspaceId`.
+- Debugging a 4xx / 5xx response.
+- Reasoning about whether a failed request will be retried.
+- Running the SDK in a browser, Cloudflare Worker, Deno, or Bun.
+
+## Base URL — the most common pitfall
+
+**The Medal Social API base URL is `https://io.medalsocial.com`.**
+
+It is NOT `https://api.medalsocial.com`. Setting `baseUrl: "https://api.medalsocial.com"` returns DNS or 404 errors. The SDK defaults to the correct value when `baseUrl` is omitted — only set it explicitly when targeting a non-prod environment.
+
+## Instantiation — token is positional
+
+The token is the **first positional argument**, not a key on an options object:
+
+```ts
+import { Medal } from "@medalsocial/sdk";
+
+// API key (recommended for server-side; scoped to one workspace)
+const medal = new Medal("medal_xxx");
+
+// OAuth access token (requires workspaceId — OAuth tokens span workspaces)
+const medal = new Medal("oauth_access_token", {
+  workspaceId: "workspace_id_here",
+});
+```
+
+`new Medal({ apiKey: ... })` is wrong — there is no `apiKey` option. The constructor throws if the token is empty.
+
+## Options
+
+```ts
+interface MedalOptions {
+  baseUrl?: string;       // defaults to https://io.medalsocial.com
+  timeout?: number;       // ms; default 30000
+  workspaceId?: string;   // required for OAuth tokens, ignored for API keys
+}
+```
+
+API keys start with `medal_` and are scoped to a single workspace — the SDK reads the workspace from the key. OAuth tokens are workspace-agnostic, so you must pass `workspaceId`.
+
+## Auth headers
+
+Every request gets:
+- `Authorization: Bearer <token>`
+- `x-workspace-id: <workspaceId>` (only if `workspaceId` was set on the constructor)
+- `User-Agent: medalsocial-sdk/<version>` (best-effort — browsers reject custom User-Agent; the SDK swallows that error silently)
+
+## Retry behavior
+
+`BaseClient.request` retries on **429 and 5xx** for up to **3 attempts total**:
+
+- If the response has a `retry-after` header (in seconds), the SDK waits that long.
+- Otherwise it waits `250 * attempt` ms (so 250, 500 between the first three attempts).
+- Other 4xx errors are NOT retried — they throw `MedalApiError` immediately.
+- Network errors (fetch throws) are NOT retried — they bubble up.
+- The request is aborted via `AbortController` after `timeout` ms.
+
+The SDK does **not** drain the response body between retries — if you observe a connection leak in long-running processes, that's worth investigating.
+
+## Errors
+
+Non-2xx responses throw `MedalApiError`:
+
+```ts
+import { Medal, MedalApiError } from "@medalsocial/sdk";
+
+try {
+  await medal.posts.create({ content: "hi", channel_ids: ["ch_1"] });
+} catch (err) {
+  if (err instanceof MedalApiError) {
+    err.status;   // HTTP status code
+    err.code;     // API error code (e.g. "INVALID_REQUEST") or "UNKNOWN_ERROR"
+    err.message;  // error.message from the API body, or "HTTP <status>: <statusText>"
+    err.details;  // optional details from the API body
+  }
+}
+```
+
+The `Medal` instance does **not** expose the underlying `BaseClient` — it's created as a local `const` in the constructor and only passed into the resource classes. There is no public way to read the resolved config from a `Medal` instance. If you need the same config later (for logging, custom requests), store your `MedalOptions` separately when you construct the client.
+
+## OIDC publishing — consumers do not need a token
+
+The package is published with provenance attestation via npm OIDC trusted publishing. Consumers do not need an `NPM_TOKEN` to install. There is no static publish token; releases run from the locked `prod` branch only via GitHub Actions.
+
+## Runtimes
+
+The SDK uses standard Web Fetch + `AbortController` and has no Node-only APIs, so it runs in Deno, Bun, Cloudflare Workers, and modern browsers.
+
+**Browser usage caveat:** the Medal API does not currently support CORS for arbitrary origins — calls from browser code typically need a server-side proxy that holds the API key. Don't embed a `medal_*` key in client-side JavaScript regardless; it grants full workspace access.
+
+**Node:** `package.json` enforces `engines.node >=24`. Older Node is blocked at install time. If you need Node 18–22 support, relax `engines` in your fork and verify against the SDK's test suite first.
+
+**Cloudflare Workers / edge:** works out of the box; the `User-Agent` set is silently rejected (workers also disallow it) and the SDK swallows the error.

package/skills/resources/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: resources
+description: Use when calling any of the SDK resources (contacts, deals, emails, gdpr, posts, workspaces) — listing with pagination, sending transactional or batch emails, scheduling and publishing posts, recording GDPR consent or running an export workflow, fetching a contact's activity timeline — or when needing OpenAPI-derived TypeScript types or the raw OpenAPI document from `@medalsocial/sdk`.
+---
+
+# Medal Social SDK — Resources
+
+## When to load this skill
+
+- Calling `medal.contacts.*`, `medal.deals.*`, `medal.emails.*`, `medal.gdpr.*`, `medal.posts.*`, or `medal.workspaces.*`.
+- Looking up an exact method signature or response shape.
+- Building a list view that needs pagination.
+- Sending a single transactional email or a bulk batch.
+- Running a GDPR data-export workflow (request → poll → fetch).
+- Importing contacts from a CSV-like source.
+- Needing OpenAPI-derived types for a custom fetch wrapper, generated mocks, or contract tests.
+
+## Response shapes
+
+Most methods return one of:
+
+- **`ApiResponse<T>`** — single-result envelope: `{ data: T }` plus optional metadata.
+- **`PaginatedResponse<T>`** — list envelope: `{ data: T[], pagination: { has_more: boolean, next_cursor: string | null } }`.
+
+**One documented exception:** `medal.gdpr.cookieConsent(input)` returns a plain `{ success: boolean, logId?: string }` directly — no `data` envelope. Don't destructure `{ data }` from it. See the GDPR section below.
+
+Errors throw `MedalApiError` (see the `client` skill for details).
+
+## Resource map
+
+| Namespace | Source | Methods |
+|---|---|---|
+| `medal.contacts` | `src/resources/contacts.ts` | `list(opts?)`, `create(input)`, `get(id)`, `update(id, input)`, `remove(id)`, `activities(id, opts?)`, `addNote(id, { content })`, `import(contacts[])` |
+| `medal.deals` | `src/resources/deals.ts` | `list(opts?)`, `create(input)`, `get(id)`, `update(id, input)`, `remove(id)` |
+| `medal.emails.templates` | `src/resources/emails.ts` (`EmailTemplates`) | `list()`, `get(slug, opts?)` |
+| `medal.emails` | `src/resources/emails.ts` (`Emails`) | `send(input)`, `get(id)`, `batch(input)` |
+| `medal.gdpr` | `src/resources/gdpr.ts` | `requestExport()`, `listExports()`, `getExport(id)`, `recordConsent(input)`, `getConsent(email)`, `cookieConsent(input)` |
+| `medal.posts` | `src/resources/posts.ts` | `list(opts?)`, `create(input)`, `get(id)`, `update(id, input)`, `remove(id)`, `schedule(id, input)`, `publish(id)`, `channels()` |
+| `medal.workspaces` | `src/resources/workspaces.ts` | `list()` |
+
+**Note on naming:** `contacts.remove(id)` is `remove`, not `delete` — `delete` is a reserved word and was avoided. Same for `deals.remove(id)`, `posts.remove(id)`.
+
+## Contacts
+
+```ts
+import { Medal } from "@medalsocial/sdk";
+const medal = new Medal("medal_xxx");
+
+// List with filters (paginated)
+const { data: contacts, pagination } = await medal.contacts.list({ status: "lead" });
+
+// Create
+const { data: contact } = await medal.contacts.create({
+  email: "alice@example.com",
+  first_name: "Alice",
+});
+
+// Add a note to the contact's timeline — input is { content }, NOT { body }
+await medal.contacts.addNote(contact.id, { content: "Followed up via email" });
+
+// Fetch the activity timeline (paginated; events include notes, deals, emails, etc.)
+const { data: activities } = await medal.contacts.activities(contact.id, { limit: 50 });
+
+// Bulk import — MAX 500 contacts per call; duplicates are skipped server-side
+await medal.contacts.import([
+  { email: "a@x.com", first_name: "A" },
+  { email: "b@x.com", first_name: "B" },
+]);
+```
+
+## Posts — create, schedule, publish
+
+```ts
+// List channels first to know what channel_ids to target
+const { data: channels } = await medal.posts.channels();
+
+// Create
+const { data: post } = await medal.posts.create({
+  content: "Hello world!",
+  channel_ids: [channels[0].id],
+});
+
+// Schedule for a future ISO 8601 timestamp
+await medal.posts.schedule(post.id, { scheduled_at: "2026-06-15T10:00:00Z" });
+
+// Or publish immediately (no schedule)
+await medal.posts.publish(post.id);
+```
+
+`channels()` is the canonical way to discover what publishing destinations a workspace has connected — don't hard-code channel IDs.
+
+## Emails — transactional + batch
+
+**Single send (HTTP 202 — queued, not delivered):**
+
+```ts
+const { data: result } = await medal.emails.send({
+  template_slug: "welcome",
+  to: "user@example.com",
+  name: "Alice",
+  locale: "en",
+  fallback_locale: "en",
+  variables: { name: "Alice", trial_days: "14" },
+  contact_id: contact.id,                // optional — links the send to a contact
+});
+// result.status is "queued"; poll medal.emails.get(result.id) for delivery state
+```
+
+**Templates:**
+
+```ts
+const { data: templates } = await medal.emails.templates.list();
+const { data: detail } = await medal.emails.templates.get("welcome", { locale: "en" });
+```
+
+**Batch send (same template to many recipients) — MAX 100 recipients per call:**
+
+```ts
+const { data: summary } = await medal.emails.batch({
+  template_slug: "newsletter-may",
+  default_locale: "en",
+  recipients: [
+    { email: "a@x.com", name: "A", variables: { unsubscribe_token: "..." } },
+    { email: "b@x.com", name: "B", locale: "fr", variables: { unsubscribe_token: "..." } },
+  ],
+});
+// summary = { batch_id, total, queued, failed }
+```
+
+For more than 100 recipients, chunk into multiple `batch()` calls. There is no built-in chunker.
+
+## GDPR — consent + export workflow
+
+**Consent (per-contact):**
+
+```ts
+await medal.gdpr.recordConsent({
+  email: "user@example.com",
+  consent_type: "marketing_email",
+  granted: true,
+});
+const { data: history } = await medal.gdpr.getConsent("user@example.com");
+```
+
+**Cookie consent** has a distinct return shape: `{ success: boolean, logId?: string }` — not the `ApiResponse<T>` envelope. Don't try to destructure `.data` from it.
+
+```ts
+const result = await medal.gdpr.cookieConsent({ /* ... */ });
+result.success; // boolean
+```
+
+**Export workflow** — async; you initiate, then poll:
+
+```ts
+const { data: req } = await medal.gdpr.requestExport();
+// req = { request_id, status }
+
+// Poll until terminal. GdprExport.status is one of:
+//   "pending" | "in_progress" | "completed" | "failed" | string
+// "completed" is success; "failed" is terminal failure; anything else is still running.
+async function waitForExport(id: string) {
+  while (true) {
+    const { data: exp } = await medal.gdpr.getExport(id);
+    if (exp.status === "completed") return exp;
+    if (exp.status === "failed") throw new Error(`Export ${id} failed`);
+    await new Promise((r) => setTimeout(r, 5_000));
+  }
+}
+const exp = await waitForExport(req.request_id);
+// exp.download_url and exp.expires_at are populated once completed
+
+// Or list everything the workspace has ever exported
+const { data: all } = await medal.gdpr.listExports();
+```
+
+## Pagination — concrete loop
+
+`PaginationOptions` is `{ limit?: number, cursor?: string }`. To page through everything:
+
+```ts
+async function listAllContacts() {
+  const out: Contact[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await medal.contacts.list({ limit: 200, cursor });
+    out.push(...page.data);
+    cursor = page.pagination.has_more ? page.pagination.next_cursor ?? undefined : undefined;
+  } while (cursor);
+  return out;
+}
+```
+
+`has_more` is the loop condition; `next_cursor` is what you pass on the next call. Don't loop on `next_cursor` alone — the API can return `has_more: false` with a non-null cursor when paging ends.
+
+## OpenAPI types — for raw fetch, mocks, or custom wrappers
+
+The package ships OpenAPI-derived types via a dedicated subpath:
+
+```ts
+import type { paths, components } from "@medalsocial/sdk/openapi-types";
+
+type GetContactsResponse =
+  paths["/contacts"]["get"]["responses"]["200"]["content"]["application/json"];
+
+type Contact = components["schemas"]["Contact"];
+```
+
+Use these when building a custom fetch wrapper (e.g. in an edge function where you want zero dependencies), generating mocks for tests, or extending the SDK with a not-yet-wrapped endpoint.
+
+## OpenAPI document — for codegen, docs, contracts
+
+The raw OpenAPI 3.1 document is exported too:
+
+```ts
+// ESM import attributes (Node 24+, modern bundlers)
+import openapi from "@medalsocial/sdk/openapi.json" with { type: "json" };
+
+// or read the YAML directly from disk (Node)
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const yamlPath = fileURLToPath(new URL("./node_modules/@medalsocial/sdk/openapi/medal-social.openapi.yaml", import.meta.url));
+const yaml = readFileSync(yamlPath, "utf8");
+```
+
+The `with { type: "json" }` import-attribute syntax requires Node 24+ or a bundler with import-attribute support (Vite, esbuild, Webpack 5+). For older runtimes, read the JSON via `fs` instead.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Correct approach |
+|---|---|---|
+| `medal.contacts.delete(id)` | Method is `remove`, not `delete` (`delete` is reserved) | `medal.contacts.remove(id)` |
+| `medal.contacts.addNote(id, { body })` | Input shape is `{ content }`, not `{ body }` | `medal.contacts.addNote(id, { content })` |
+| `new Medal({ apiKey: "..." })` | Token is positional, not an option | `new Medal("medal_xxx")` |
+| `medal.emails.list()` | Templates live at `medal.emails.templates.list()`; `emails.list()` doesn't exist | `medal.emails.templates.list()` |
+| Treating `cookieConsent` result like `ApiResponse<T>` | Returns `{ success, logId? }` directly, not wrapped in `{ data }` | Read `result.success` directly |
+| Treating `emails.send` as confirmation of delivery | API returns HTTP 202; status is `"queued"` | Poll `medal.emails.get(result.id)` for delivery state |
+| `emails.batch` with > 100 recipients | API rejects; no client-side chunking | Chunk into 100-recipient batches yourself |
+| `contacts.import` with > 500 contacts | API rejects | Chunk into 500-contact batches yourself |
+| Hard-coded channel IDs in `posts.create` | Channels are workspace-specific | Call `posts.channels()` to discover them |
+| Looping on `next_cursor` alone for pagination | Can be non-null when `has_more: false` | Loop on `pagination.has_more` |
+| Building a custom client when only types are needed | Reinventing the wheel | Import from `@medalsocial/sdk/openapi-types` |