@softr/sdk 0.0.26-alpha-0 → 0.0.27

package/package.json

@@ -1,36 +1,16 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.26-alpha-0",
+  "version": "0.0.27",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
-    },
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js"
-    },
-    "./vite": {
-      "types": "./dist/vite.d.ts",
-      "import": "./dist/vite.js"
-    }
-  },
-  "bin": {
-    "softr-sdk": "./dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "skills",
-    "!skills/_artifacts"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
+    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
+    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
+  },
+  "bin": { "softr-sdk": "./dist/cli.js" },
+  "files": ["dist", "skills", "!skills/_artifacts"],
+  "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
@@ -62,9 +42,7 @@
       "optional": true
     }
   },
-  "keywords": [
-    "tanstack-intent"
-  ],
+  "keywords": ["tanstack-intent"],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

package/skills/softr-sdk/SKILL.md

@@ -5,13 +5,13 @@ description: >-
   four entrypoints (@softr/sdk, /server, /client, /vite) and the client-server
   boundary between them, softrAuthMiddleware, getSoftrContext,
   initialSoftrContext, SoftrContext, and which sub-skill to load for route
-  visibility, the current user, reading records, charts and metrics, writing
-  records, or auth. Load this when unsure which sub-skill applies, or when
-  touching the wiring; each sub-skill stands alone for its own task.
+  visibility, the current user, reading records, writing records, or auth. Load
+  this when unsure which sub-skill applies, or when touching the wiring; each
+  sub-skill stands alone for its own task.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.25
+  library_version: 0.0.27
 ---
 
 # Softr SDK core
@@ -21,7 +21,7 @@ metadata:
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 > **CRITICAL**: Every route file must declare its audience with `defineVisibility`. There is no default and nothing is inherited from a sibling. A route file without a declaration is a lint error.
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register the middleware and resolve the session. Do not add a second registration.
-> **CRITICAL**: `workflow.trigger` and `integration.fetch` are exploratory. They exist on the entrypoints below and they typecheck, but their endpoints are not final. Do not build a feature on either of them. Tell the user the capability is not ready and ask how they want to proceed.
+> **CRITICAL**: `workflow.trigger` is exploratory. It exists on the entrypoints below and typechecks, but its endpoint is not final. Do not build a feature on it. Tell the user the capability is not ready and ask how they want to proceed.
 
 Each sub-skill stands alone for its task and repeats the boundary above, so most work needs **one** sub-skill and not this file. Load this one when you are unsure which sub-skill applies, or when the wiring below is what you are touching. Add a second sub-skill only when the work genuinely crosses that boundary: a page that lists records behind a group restriction needs `reading-records` plus `routes-and-visibility`.
 
@@ -29,7 +29,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineAction`, `defineVisibility`, `useCurrentUser`, `usePermissions`, `useUserTimezone`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineVisibility`, `q`, `useCurrentUser`, `usePermissions`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -41,9 +41,9 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Add a route, or change who can see one | [routes-and-visibility/SKILL.md](./routes-and-visibility/SKILL.md) |
 | Read the signed-in visitor or what they may do | [current-user/SKILL.md](./current-user/SKILL.md) |
 | Fetch records from a datasource | [reading-records/SKILL.md](./reading-records/SKILL.md) |
-| Chart, aggregate or count records | [charts-and-metrics/SKILL.md](./charts-and-metrics/SKILL.md) |
 | Create, update or delete a record | [data-mutations/SKILL.md](./data-mutations/SKILL.md) |
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
+| Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
 
 ## Quick Decision Tree
 
@@ -57,15 +57,15 @@ Showing the visitor's name, or hiding UI they cannot use?
 Putting records on a page, in a table, a list or a detail view?
   load softr-sdk/reading-records
 
-Drawing a chart, a stat tile, or any aggregated number?
-  load softr-sdk/charts-and-metrics
-
 Submitting a form, editing a record, or deleting one?
   load softr-sdk/data-mutations
 
 Wiring a login, signup, or sign-out?
   load softr-sdk/auth
 
+Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)?
+  load softr-sdk/integrations
+
 Writing a server function, loader, or middleware in general?
   not a Softr concern. Use the TanStack Start skills.
 ```
@@ -128,4 +128,4 @@ type User = {
 
 ## Version
 
-Targets `@softr/sdk` v0.0.25.
+Targets `@softr/sdk` v0.0.26.

package/skills/softr-sdk/auth/SKILL.md

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.25
+  library_version: 0.0.27
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineVisibility`, the hooks and every type come from `@softr/sdk`. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/current-user/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.25
+  library_version: 0.0.27
 ---
 
 **Boundary.** `useCurrentUser`, `usePermissions` and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/data-mutations/SKILL.md

@@ -2,14 +2,13 @@
 name: data-mutations
 description: >-
   Create, update and delete records in a Softr datasource from inside a server
-  function: declaring a write with defineAction, ds.create, ds.update and
-  ds.delete from @softr/sdk/server, the data payload keyed by the action's
-  aliases, what each field type accepts on a write, and the record each call
-  returns. Writes only. Reads, charts and metrics are not covered.
+  function: ds.create, ds.update and ds.delete from @softr/sdk/server, the data
+  payload key, select field aliasing on the way in and out, and what each call
+  returns or throws. Writes only. Reads, metrics and chart data are not covered.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.25
+  library_version: 0.0.27
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `q` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -23,101 +22,93 @@ metadata:
 ```ts
 import { createServerFn } from '@tanstack/react-start'
 import { z } from 'zod'
-import { defineAction } from '@softr/sdk'
 import { ds } from '@softr/sdk/server'
+import { q } from '@softr/sdk'
 ```
 
-A write's input arrives from the client, so validate it. Pass a zod schema straight to `.validator`; Start accepts it and types `data` from it.
+Pass a zod schema straight to `.validator`. Start accepts it and types `data` from it.
 
-## Declare the write
+Every `ds` call names its datasource by an opaque UUID from the table's registration on the application (Softr Studio's Data tab, or the `register_application_data_source` tool when an agent does it). It is never derived from the table's name. Field ids are opaque too (`fZk3Qm9pLw2Xa1`, not `fld_<name>`) and come from the table's schema.
 
-Every `ds` call takes an action, and an action declares one operation. A create action only works with `ds.create`; hand it to `ds.update` and the call throws `action "createProject" is declared as create, not update`.
-
-```ts
-const createProject = defineAction({
-  id: 'createProject',
-  datasource: 'c9a51f22-3b8e-4d17-a6c0-5e92d84b7f31',
-  operation: 'create',
-  fields: {
-    name: 'fZk3Qm9pLw2Xa1',    // SINGLE_LINE_TEXT
-    status: 'Ru7bVx2cNq0Ed9',  // SELECT, choice ids 'draft' | 'active' | 'archived'
-    dueDate: 'Xp2dLh6vKz9Fa3', // DATETIME
-  },
-  permission: { userGroup: 'LOGGED_IN_USERS' },
-})
-```
-
-The declaration follows the same rules as a read action, spelled out in [reading-records](../reading-records/SKILL.md): `datasource` is the opaque UUID from the table's registration, never derived from its name; the keys of `fields` are names you choose and the values are opaque field ids; everything sits at module scope with every property a literal.
-
-The action's `fields` bound the write: `data` can only name them, and the returned record only carries them. A delete action declares no `fields`; giving it some is a type error.
+**The datasource id must be a string literal at the call site.**
 
 ## Core Patterns
 
 ### Create a record
 
 ```ts
-const NewProject = z.object({ name: z.string(), dueDate: z.string() })
+const NewProject = z.object({ name: z.string(), status: z.string() })
 
-const addProject = createServerFn({ method: 'POST' })
+const createProject = createServerFn({ method: 'POST' })
   .validator(NewProject)
   .handler(async ({ data }) =>
-    ds.create(createProject, {
-      data: { name: data.name, dueDate: data.dueDate, status: { id: 'draft' } },
+    ds.create('8ffb4814-b028-4496-b679-7face2167ebc', {
+      data,
+      select: q.select({ name: 'fZk3Qm9pLw2Xa1', status: 'Ru7bVx2cNq0Ed9' }),
     }),
   )
 ```
 
-Returns the created record as `{ id, fields }`, with `fields` keyed by the action's names and holding the same value shapes a read returns. Every key in `data` is optional. A field left out, or written as `null`, gets the datasource's default.
+Resolves to `{ id, fields }`, and on a Softr table `fields` holds **only the keys you wrote** — not the rest of the record. See "What a write answers with" below.
+
+**The payload key is `data`, not `fields`.** A record answers with `fields`, which is where the confusion comes from, but the option you pass is `data`. `CreateOptions` requires it, so a call keyed by `fields` does not type-check.
+
+**`data` speaks whatever `select` maps.** The keys above are the schema's own names because `select` maps them to field ids, which is why the validated input can go straight through. With no `select`, `data` has to be keyed by raw field ids instead.
 
 ### Update a record
 
 ```ts
-const updateProject = defineAction({
-  id: 'updateProject',
-  datasource: 'c9a51f22-3b8e-4d17-a6c0-5e92d84b7f31',
-  operation: 'update',
-  fields: { status: 'Ru7bVx2cNq0Ed9', dueDate: 'Xp2dLh6vKz9Fa3' },
-  permission: { userGroup: 'LOGGED_IN_USERS' },
-})
-
-const archiveProject = createServerFn({ method: 'POST' })
-  .validator(z.object({ id: z.string() }))
+const Rename = z.object({ id: z.string(), name: z.string() })
+
+const renameProject = createServerFn({ method: 'POST' })
+  .validator(Rename)
   .handler(async ({ data }) =>
-    ds.update(updateProject, { id: data.id, data: { status: { id: 'archived' } } }),
+    ds.update('8ffb4814-b028-4496-b679-7face2167ebc', {
+      id: data.id,
+      data: { name: data.name },
+      select: q.select({ name: 'fZk3Qm9pLw2Xa1' }),
+    }),
   )
 ```
 
-The record id is its own option; keep it out of `data`. An empty `id` throws.
+The record id is its own option, so keep it out of `data`.
+
+`update` writes the keys in `data` and leaves every other field alone, so a field you leave out is a field you are not writing. An empty `id` throws.
+
+### What a write answers with
+
+`create` and `update` resolve to `{ id, fields }`, but `fields` is **not the record**. On a Softr table it carries only the keys you sent, aliased through `select`; a status change answers with `{ id, fields: { status } }` and nothing else. (Other datasource types may answer with more. Rely on neither.)
 
-`update` writes the keys in `data` and leaves every other field alone, so a field you leave out is a field you are not writing. On an update, `null` clears the field, where on a create it reached the default. Returns the updated record.
+So the answer is a receipt, not a replacement for what the page holds. Putting it where a loader-fetched record was blanks every column you did not write. Two honest ways to show the result:
+
+- **A quick change to one field** — a status select, a card dragged to another column, an archive toggle — is optimistic: change that one field in your own state immediately, keep the rest of the record as the loader gave it, save in the background, and on a rejected write restore the old value with a clear message. Do not `router.invalidate()` or re-fetch after a successful write; the local change is already what the user sees.
+- **A saved form, or anything that changes several fields**, refreshes the route's data — `router.invalidate()`, see `@tanstack/router-core#router-core/data-loading` — so the list or detail re-reads through its own `select`.
+
+Do not re-read the one record with `ds.get` for either: it takes no `select`, so it answers with raw field ids.
+
+### Writing a choice field
+
+A `SELECT` or `LINKED_RECORD` field reads back as `{ id, label }` (see [field-types](../reading-records/references/field-types.md)). Writing one accepts the option's `id`, its `label`, or `{ id, label }`, matched case-insensitively.
+
+**A value that matches no option is not an error — it silently adds a new option to the field.** A typo'd label leaves a junk choice in the schema. So write `{ label }` (or the `{ id, label }` you read), copy labels from the table's schema verbatim, and never invent one.
 
 ### Delete a record
 
 ```ts
-const deleteProject = defineAction({
-  id: 'deleteProject',
-  datasource: 'c9a51f22-3b8e-4d17-a6c0-5e92d84b7f31',
-  operation: 'delete',
-  permission: { userGroup: 'LOGGED_IN_USERS' },
-})
-
-const removeProject = createServerFn({ method: 'POST' })
-  .validator(z.object({ id: z.string() }))
-  .handler(async ({ data }) => {
-    await ds.delete(deleteProject, { id: data.id })
-  })
+const RecordId = z.object({ id: z.string() })
+
+const deleteProject = createServerFn({ method: 'POST' })
+  .validator(RecordId)
+  .handler(async ({ data }) => ds.delete('8ffb4814-b028-4496-b679-7face2167ebc', data.id))
 ```
 
-Resolves to nothing. A record that cannot be deleted throws.
+**`delete` takes the record id as a positional argument**, unlike `create` and `update`, which take an options object. It resolves to nothing.
 
-### What a write accepts
+### Naming fields with `select`
 
-With `softr-env.d.ts` in place (see [reading-records](../reading-records/SKILL.md#typing)), each key of `data` accepts exactly what its field takes:
+`select` works in both directions on a write. Going in, it turns your names into Softr field ids. Coming back, it turns the returned field ids into your names. Without it, `data` has to be keyed by raw field ids and the returned record answers with them too.
 
-- SELECT and LINKED_RECORD take `{ id }`. Not a bare string, and not the `{ id, label }` a read returns; the label is display data and a write does not accept it. A generated SELECT narrows the id to the field's own choices.
-- CHECKBOX takes a boolean. Dates take ISO strings, never `Date` instances.
-- ATTACHMENT takes `{ url }`, optionally with `filename`, `id` and `type`.
-- A multi-entry field takes an array of the value.
+The map has to cover every key in `data`. A key it does not map is not translated, so the write does not land on the field you meant.
 
 ### Writing on behalf of the visitor
 
@@ -125,16 +116,6 @@ Stamping a record with who created it, or scoping an update to the person making
 
 ## Failure Modes
 
-**A write with the wrong action.** Each operation needs an action declared for it. `ds.update` with a read action throws `action "..." is declared as read, not update` at the first call, not at build time.
-
-**A payload keyed `fields`.** The option is `data`. A record answers with `fields`, which is where the confusion comes from, but the option you pass is `data`, and the options type requires it.
-
-**A SELECT or LINKED_RECORD written as a bare string.** The write shape is `{ id }`. Writing `status: 'archived'` where `status: { id: 'archived' }` belongs is a type error with codegen in place and a silent misfire without it.
-
-**Feeding a read value back into a write.** A read returns `{ id, label }`; a write takes `{ id }` only. Strip the label before writing the value back.
-
-**A field missing from the action.** `data` can only name the action's own `fields`. A field you need to write must be declared on the action, and a delete action declares none.
-
 **A datasource id built from a name.** `'ds_projects'`, the table id, or the table's name glued to a uuid are not datasource ids. The id is the opaque UUID assigned when the table was registered on the application; copy it from there. Anything else fails at request time as not found or forbidden.
 
 **A datasource id stored in a variable.** Pass the UUID as a string literal directly at the call site. The lint rule `@softr/ds-no-computed-id` catches this at development time.
@@ -153,6 +134,5 @@ Stamping a record with who created it, or scoping an update to the person making
 
 ## References
 
-- [reading-records/SKILL.md](../reading-records/SKILL.md): declaring actions, fetching the record a write is about to change, and the codegen the types come from
-- [reading-records/references/field-types.md](../reading-records/references/field-types.md): the value shape every field reads back as
+- [reading-records/SKILL.md](../reading-records/SKILL.md): fetching the record a write is about to change
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context` to stamp or scope a write

package/skills/softr-sdk/integrations/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: integrations
+description: >-
+  Call a third-party service connected to the app as an integration: integration.fetch
+  from @softr/sdk/server, reading the datasource id and integration type from the
+  "Attached data sources" prompt section, looking up the base URL from the reference
+  table by integrationType, and constructing the full API URL from base URL plus the
+  path and query params the model knows from training. Check res.ok before res.json().
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.27
+---
+
+**Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+
+# Integrations
+
+`integration.fetch` calls a third-party API through Softr's authenticated proxy. It handles authorization automatically — you never set API keys or auth headers yourself.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { integration } from '@softr/sdk/server'
+```
+
+## Reading connected integrations from the prompt
+
+When the user attaches integrations to the chat, they appear in the `## Attached data sources` section of the prompt in this form:
+
+```
+- "Gmail" — database `<databaseId>`, integration `<integrationId>`, type `GMAIL`
+```
+
+Use `databaseId` as the first argument to `integration.fetch`. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL by appending the path and query parameters your training knows for that API.
+
+## Core pattern
+
+```ts
+const getCalendarEvents = createServerFn().handler(async () => {
+  const now = new Date().toISOString()
+  const res = await integration.fetch(
+    '25d60213-ef4f-4fa0-b094-a46931b2d120',
+    `https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=${encodeURIComponent(now)}&singleEvents=true&orderBy=startTime&maxResults=10`,
+  )
+  if (!res.ok) throw new Error(`Integration request failed: ${res.status} ${await res.text()}`)
+  return res.json()
+})
+```
+
+The id (`25d60213-…`) is the `databaseId` from the attached data sources section. The base URL (`https://www.googleapis.com`) is looked up from the reference table below by matching `integrationType` (`GOOGLE_CALENDAR`). The path and query params come from your knowledge of the Google Calendar REST API.
+
+## POST request
+
+```ts
+const sendSlackMessage = createServerFn({ method: 'POST' })
+  .validator((data: { channel: string; text: string }) => data)
+  .handler(async ({ data }) => {
+    const res = await integration.fetch(
+      'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+      'https://slack.com/api/chat.postMessage',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ channel: data.channel, text: data.text }),
+      },
+    )
+    if (!res.ok) throw new Error(`Slack error: ${res.status} ${await res.text()}`)
+    return res.json()
+  })
+```
+
+`integration.fetch` accepts the same `RequestInit` options as the native `fetch`. Do not pass `Authorization` headers — Softr injects the integration's credentials automatically.
+
+## Base URLs by integration type
+
+Match the `integrationType` from the attached data sources section to find the base URL:
+
+| integrationType | Base URL |
+|---|---|
+| ANTHROPIC_AI | `https://api.anthropic.com` |
+| APOLLO | `https://api.apollo.io` |
+| APIFY | `https://api.apify.com` |
+| ASANA | `https://app.asana.com` |
+| ATTIO | `https://api.attio.com` |
+| BASEROW | `https://api.baserow.io` |
+| BITLY | `https://api-ssl.bitly.com` |
+| BREVO | `https://api.brevo.com` |
+| CALCOM | `https://api.cal.com` |
+| CALENDLY | `https://api.calendly.com` |
+| COHERE | `https://api.cohere.com` |
+| DEEPL | `https://api.deepl.com` |
+| DEEP_SEEK_AI | `https://api.deepseek.com` |
+| DOCS_AUTOMATOR | `https://api.docsautomator.co` |
+| DOCUMINT | `https://api.documint.me` |
+| ELASTIC_EMAIL | `https://api.elasticemail.com` |
+| ELEVEN_LABS | `https://api.elevenlabs.io` |
+| FATHOM | `https://api.fathom.ai` |
+| FIRECRAWL | `https://api.firecrawl.dev` |
+| GEMINI_AI | `https://generativelanguage.googleapis.com` |
+| GMAIL | `https://gmail.googleapis.com` |
+| GOOGLE_CALENDAR | `https://www.googleapis.com` |
+| GRANOLA | `https://public-api.granola.ai` |
+| HUNTER | `https://api.hunter.io` |
+| INSTANTLY | `https://api.instantly.ai` |
+| LEMLIST | `https://api.lemlist.com` |
+| LINEAR | `https://api.linear.app` |
+| LINKUP | `https://api.linkup.so` |
+| LOOPS | `https://app.loops.so` |
+| MESSAGE_BIRD | `https://rest.messagebird.com` |
+| MISTRAL_AI | `https://api.mistral.ai` |
+| OPEN_AI | `https://api.openai.com` |
+| OUTLOOK | `https://graph.microsoft.com` |
+| PADDLE | `https://api.paddle.com` |
+| PINECONE | `https://api.pinecone.io` |
+| PIPELINE_CRM | `https://api.pipelinecrm.com` |
+| POSTMARK | `https://api.postmarkapp.com` |
+| REPLICATE | `https://api.replicate.com` |
+| RESEND | `https://api.resend.com` |
+| SLACK | `https://slack.com/api` |
+| SMARTLEAD | `https://server.smartlead.ai` |
+| STRIPE | `https://api.stripe.com` |
+| TELEGRAM | `https://api.telegram.org` |
+| TINYURL | `https://api.tinyurl.com` |
+| TWILIO | `https://api.twilio.com` |
+| XERO | `https://api.xero.com` |
+| ZOOM | `https://api.zoom.us` |
+
+## When the service is not a Softr integration
+
+If the API the user needs is not in the table above, call it directly from a server function using the native `fetch`. The user supplies their own credentials and the call lives entirely in the server function handler.
+
+## Failure modes
+
+**Calling from client code.** `integration` is server-only. Importing it into a component or calling it outside a `createServerFn` handler fails the build or has no request context to act on.
+
+**Setting Authorization headers.** Softr injects credentials automatically. A manually set `Authorization` header overrides the injected one and the request is rejected by the third-party API.
+
+**Not checking `res.ok`.** `integration.fetch` returns the proxied response as-is. A 4xx or 5xx from the third-party API is not thrown — call `res.ok` or `res.status` before calling `res.json()`.