@softr/sdk 0.0.28 → 0.0.30-alpha.0

package/dist/core/integration.d.ts

@@ -1,5 +1,22 @@
 //#region src/core/integration.d.ts
-declare function integrationFetch(datasourceId: string, input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+interface IntegrationFetchOptions {
+  dataSourceId: string;
+  url: string;
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+  queryParams?: Record<string, string>;
+  signal?: AbortSignal;
+}
+declare function integrationFetch({
+  dataSourceId,
+  url: rawUrl,
+  method,
+  headers,
+  body,
+  queryParams,
+  signal
+}: IntegrationFetchOptions): Promise<Response>;
 declare const integration: {
   fetch: typeof integrationFetch;
 };

package/dist/core/integration.js

@@ -2,28 +2,28 @@ import { readSessionToken } from "../auth/session.js";
 import { dsUrl } from "../datasource/record.js";
 
 //#region src/core/integration.ts
-async function integrationFetch(datasourceId, input, init) {
-	const req = new Request(input, init);
-	if (req.signal.aborted) throw req.signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
-	const reqHeaders = {};
-	new Headers(req.headers).forEach((value, key) => {
-		reqHeaders[key] = value;
-	});
+async function integrationFetch({ dataSourceId, url: rawUrl, method = "GET", headers = {}, body, queryParams, signal }) {
+	if (signal?.aborted) throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+	let url = rawUrl;
+	if (queryParams && Object.keys(queryParams).length > 0) {
+		const params = new URLSearchParams(queryParams);
+		url += (rawUrl.includes("?") ? "&" : "?") + params.toString();
+	}
+	const upperMethod = method.toUpperCase();
 	const payload = {
-		method: req.method,
-		url: req.url,
-		headers: reqHeaders
+		method: upperMethod,
+		url,
+		headers
 	};
-	const method = req.method.toUpperCase();
-	if (method !== "GET" && method !== "HEAD" && req.body !== null) payload.body = await req.clone().text();
-	return fetch(`${dsUrl(datasourceId)}/proxy`, {
+	if (upperMethod !== "GET" && upperMethod !== "HEAD" && body !== void 0) payload.body = body;
+	return fetch(`${dsUrl(dataSourceId)}/proxy`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
 			"Authorization": `Bearer ${readSessionToken()}`
 		},
 		body: JSON.stringify(payload),
-		signal: req.signal
+		signal
 	});
 }
 const integration = { fetch: integrationFetch };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.28";
+var version = "0.0.30-alpha.0";
 
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.28",
+  "version": "0.0.30-alpha.0",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

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, 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, 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.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.28
+  library_version: 0.0.29
 ---
 
 # Softr SDK core
@@ -23,13 +23,13 @@ metadata:
 > **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` 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`.
+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 `record-queries` plus `routes-and-visibility`.
 
 ## Entrypoints
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineVisibility`, `q`, `useCurrentUser`, `usePermissions`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `useCurrentUser`, `usePermissions`, `useUserTimezone`, `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` |
@@ -40,8 +40,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) |
-| Create, update or delete a record | [data-mutations/SKILL.md](./data-mutations/SKILL.md) |
+| Fetch records from a datasource | [record-queries/SKILL.md](./record-queries/SKILL.md) |
+| Chart, aggregate or count records | [charts-and-metrics/SKILL.md](./charts-and-metrics/SKILL.md) |
+| Create, update or delete a record | [record-mutations/SKILL.md](./record-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) |
 
@@ -55,10 +56,13 @@ Showing the visitor's name, or hiding UI they cannot use?
   load softr-sdk/current-user
 
 Putting records on a page, in a table, a list or a detail view?
-  load softr-sdk/reading-records
+  load softr-sdk/record-queries
+
+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
+  load softr-sdk/record-mutations
 
 Wiring a login, signup, or sign-out?
   load softr-sdk/auth
@@ -125,7 +129,3 @@ type User = {
   userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
 }
 ```
-
-## Version
-
-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.28
+  library_version: 0.0.29
 ---
 
 **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/charts-and-metrics/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: charts-and-metrics
+description: >-
+  Aggregate Softr datasource records inside a server function: ds.chart with
+  groupBy, metrics, where and orderBy for chart rows, ds.metric for a single
+  headline number, date bucket intervals, which aggregations each kind of field
+  offers, the two-group-column ceiling, and distinct values for filter controls.
+  Use when drawing a chart, a stat tile or any counted, summed or averaged
+  number, when filling a dropdown from a real column, or when a chart comes back
+  scrambled or with the wrong rows. Aggregation only: fetching individual
+  records is record-queries, and changing them is record-mutations.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.29
+---
+
+**Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` 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.
+
+# Charts and metrics
+
+`ds.chart` groups records and aggregates each group into one row: the data behind a bar chart, a line, a pie. `ds.metric` aggregates everything into one value: the number on a stat tile. Both live on `@softr/sdk/server` and run inside a `createServerFn` handler, and both take the same query `ds.list` takes, with the same `where` filters.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { defineQuery } from '@softr/sdk'
+import { ds } from '@softr/sdk/server'
+
+const sales = defineQuery({
+  id: 'sales',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  fields: {
+    amount: 'Vk9cXm2pSz6Ld4',   // CURRENCY
+    region: 'fZk3Qm9pLw2Xa1',   // SELECT
+    status: 'Ru7bVx2cNq0Ed9',   // SELECT, choice ids 'paid' | 'open' | 'void'
+    closedAt: 'Xp2dLh6vKz9Fa3', // DATETIME
+    rep: 'Gq5wNt8rJy3Hb1',      // LINKED_RECORD
+  },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+```
+
+A chart only sees the query's declared fields, so a field to group, aggregate or filter by must be in `fields`. Declaring a query belongs to [record-queries](../record-queries/SKILL.md); one query serves `ds.list`, `ds.chart` and `ds.metric`.
+
+## Core Patterns
+
+### A bar chart
+
+```ts
+const ordersByRegion = createServerFn().handler(async () => {
+  const { data } = await ds
+    .chart(sales)
+    .groupBy((q) => ({ region: q.region }))
+    .metrics((q) => ({ orders: q.$count }))
+    .orderBy((q) => q.orders.desc)
+  return data
+})
+// data: Array<{ region: string | null; orders: number }>
+```
+
+One row per group, keyed by the names you chose in `groupBy` and `metrics`. `orders` is `number`, not `number | null`: a group that exists holds at least one record. The `null` region is the bucket of records with no value. The result also carries `executionTimestamp: Date`, when the numbers were computed.
+
+A SELECT or LINKED_RECORD group column comes back as the choice's display label, not its id. Labels are user-editable and a `where` on the same field compares ids, so a clicked bar's value cannot be fed straight back into a filter.
+
+### A time series
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ month: q.closedAt.byMonth }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .where((q) => q.status.is('paid'))
+  .orderBy((q) => q.month.asc)
+// data: Array<{ month: string | null; revenue: number | null }>
+```
+
+`q.closedAt` bare groups by the field's value. The bucket leaves hanging off it group a date field by the bucket: `byDay`, `byWeek`, `byMonth`, `byQuarter`, `byYear`, and the cyclic `byHourOfDay`, `byDayOfWeek`, `byMonthOfYear`, `byQuarterOfYear`. What each one holds is in [references/aggregations.md](./references/aggregations.md); `byMonth` reads as `"2025-06"`.
+
+**Sort the time axis ascending yourself.** Left unsorted, rows come back by the first bucket ascending when there is one, else by the first metric descending. A time axis that misses the fallback arrives in value order, which draws a scrambled line rather than failing.
+
+### Spread, not just totals
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ region: q.region }))
+  .metrics((q) => ({
+    smallest: q.amount.min,
+    typical: q.amount.avg,
+    biggest: q.amount.max,
+  }))
+  .orderBy((q) => q.typical.desc)
+```
+
+Any number of metrics in one request, several over the same field included. Each row carries all of them, so one request can feed two panels. A metric key may not reuse a group key, and two metrics may not ask for the same value. `avg` comes back rounded to two decimals.
+
+### Two group columns, which is the ceiling
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ month: q.closedAt.byMonth, region: q.region }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .orderBy((q) => [q.month.asc, q.revenue.desc])
+// data: Array<{ month: string | null; region: string | null; revenue: number | null }>
+```
+
+The result is long format, one row per month and region pair, so the app pivots into one array per series before charting. **A chart groups by at most two columns**, each a different field, and a field cannot be grouped and aggregated in the same chart. A third group column is a compile error.
+
+### Distinct values, for a filter control
+
+```ts
+const { data } = await ds.chart(sales).groupBy((q) => ({ region: q.region }))
+// data: Array<{ region: string | null }>
+```
+
+Skip `metrics` entirely and the rows hold the distinct group values, one each. This is the cheapest way to fill a dropdown from a real column.
+
+### A headline number
+
+```ts
+const { value } = await ds
+  .metric(sales, (q) => q.amount.sum)
+  .where((q) => q.status.is('paid'))
+// value: number | null
+```
+
+One aggregation, no grouping, one value. Whenever the answer is a single number, a stat tile or a count, reach for `ds.metric` rather than a one-row chart: there is nothing to group by and nothing to unpack out of `data`. The same measure handles apply, `q.$count` included:
+
+```ts
+const { value: open } = await ds.metric(sales, (q) => q.$count).where((q) => q.status.is('open'))
+// open: number
+```
+
+### Top N
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ rep: q.rep }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .orderBy((q) => q.revenue.desc)
+
+const top5 = data.slice(0, 5)
+```
+
+A chart has no row limit to set, so a top-N is a client-side slice of the fully sorted rows.
+
+### A dashboard load
+
+```ts
+const loadDashboard = createServerFn().handler(async () => {
+  const [mtd, series] = await Promise.all([
+    ds
+      .metric(sales, (q) => q.amount.sum)
+      .where((q) => q.$and(q.status.is('paid'), q.closedAt.gte('2026-09-01'))),
+    ds
+      .chart(sales)
+      .groupBy((q) => ({ month: q.closedAt.byMonth }))
+      .metrics((q) => ({ revenue: q.amount.sum }))
+      .where((q) => q.status.is('paid'))
+      .orderBy((q) => q.month.asc),
+  ])
+  return { mtd: mtd.value, series: series.data }
+})
+```
+
+Each tile and panel is its own request, fired in parallel from one handler.
+
+## Order of calls
+
+`groupBy` comes first and exactly once; a chart cannot be awaited before it. `metrics` follows, at most once, or not at all for distinct values. `where` can be chained anywhere, repeatedly, and calling it more than once ands the filters together. `orderBy` sorts by the chart's own keys, group and metric alike, and only sees the keys declared so far, so call it last.
+
+## References
+
+- [references/aggregations.md](./references/aggregations.md): every bucket interval and its value type, and which aggregations each kind of field offers. Load it when choosing a bucket or when a field does not offer the aggregation you expected.
+- [record-queries/SKILL.md](../record-queries/SKILL.md): declaring the query a chart aggregates over. Load it when the declaration itself is what you are writing.
+- [record-queries/references/filters-and-sorting.md](../record-queries/references/filters-and-sorting.md): every filter operator by field type. Load it when the `where` you need is not shown here, or when a filter is rejected.

package/skills/softr-sdk/charts-and-metrics/references/aggregations.md

@@ -0,0 +1,76 @@
+# Buckets, aggregations and chart rules
+
+## Group columns
+
+A bare handle in `groupBy` groups by the field's value. What the column reads back as depends on the field's declared type:
+
+| Field type | Column value |
+| --- | --- |
+| SELECT, LINKED_RECORD, CREATED_BY, UPDATED_BY | `string \| null`, the display label, not the id |
+| Text fields | `string \| null` |
+| Number fields | `number \| null` |
+| CHECKBOX | `boolean \| null` |
+| DATE, DATETIME, CREATED_AT, UPDATED_AT | `string \| null`, or a bucket leaf below |
+| Multi-value (`SELECT[]` and friends), ATTACHMENT, DATE_RANGE | Cannot group |
+
+`null` is always the bucket of records with no value. A multi-value field can neither group nor aggregate: exploding it would count each record once per value and inflate every metric.
+
+## Date buckets
+
+Leaves on every date and datetime handle, `q.closedAt.byMonth` style:
+
+| Leaf | Groups by | Column value |
+| --- | --- | --- |
+| `.byDay` | Calendar day | `"2025-06-14"` |
+| `.byWeek` | Calendar week | The ISO date of the week's Monday |
+| `.byMonth` | Calendar month | `"2025-06"` |
+| `.byQuarter` | Calendar quarter | `"Q2 2025"`, a display string, not a parseable date |
+| `.byYear` | Calendar year | The year as a `number` |
+| `.byHourOfDay` | Hour of day | `0`–`23`. DATETIME fields only, not DATE |
+| `.byDayOfWeek` | Day of week | `1`–`7`, 1 is Sunday |
+| `.byMonthOfYear` | Month of year | `1`–`12` |
+| `.byQuarterOfYear` | Quarter of year | `1`–`4` |
+
+Every bucket value is `| null` for the empty bucket. The cyclic buckets come back as bare numbers; the app supplies the labels.
+
+`byWeek` is Monday-based while `byDayOfWeek` counts from Sunday, so the two cannot be lined up by arithmetic alone.
+
+## Aggregations
+
+Handles in `metrics`, and the second argument of `ds.metric`:
+
+| Handle | Available on | Comes back as |
+| --- | --- | --- |
+| `.sum` | Number fields | `number \| null` |
+| `.avg` | Number fields | `number \| null`, rounded to two decimals |
+| `.min` / `.max` | Number fields | `number \| null` |
+| `.min` / `.max` | Date fields | `string \| null`, as `"2025-06-14"` |
+| `.distinct` | Number and date fields | `number`, the count of distinct values |
+| `q.$count` | No field: counts rows | `number` |
+
+Number fields: NUMBER, PERCENT, CURRENCY, PROGRESS, RATING, DURATION, COUNT, AUTONUMBER. Date fields: DATE, DATETIME, CREATED_AT, UPDATED_AT.
+
+Every other field offers no aggregations at all. `q.$count` is the only measure that touches no field, so a text or choice column is measured by grouping on it and counting rows.
+
+`sum`, `avg`, `min` and `max` are `null` for a group with no values. `$count` and `distinct` are plain `number`.
+
+## Rules
+
+- `groupBy` takes one or two columns, is required, and is called once. A third column, and a chart with no group columns, are compile errors.
+- Each group column is a different field, and a field cannot be grouped and aggregated in the same chart.
+- `metrics` is optional and called at most once. A metric key may not reuse a group key, and two metrics may not ask for the same aggregation of the same field.
+- `orderBy` names the chart's own keys, group and metric alike. Call it last: it only sees keys already declared.
+- Left unsorted, rows come back by the first bucket column ascending; with no bucket, by the first metric descending; with neither, by the first group ascending.
+- There is no row limit. A top-N is a client-side `slice` of the sorted rows.
+
+## Errors
+
+| Message | Cause |
+| --- | --- |
+| `a chart needs at least one column to group by` | Awaiting a chart whose `groupBy` produced no columns |
+| `a chart may group by at most two columns` | Three or more group columns |
+| `a chart may group by a field only once` | The same field twice in `groupBy` |
+| `a field cannot be grouped and aggregated in one chart` | One field in both `groupBy` and `metrics` |
+| `two metrics ask for the same value` | The same aggregation of the same field under two keys |
+| `"..." is not a column of this chart` | An `orderBy` key that is neither a group nor a metric key |
+| `a chart column must come from the callback a chart hands you` | A hand-built object where a handle belongs |

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.28
+  library_version: 0.0.29
 ---
 
 **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.
@@ -69,7 +69,7 @@ A `guard()` in `beforeLoad` guarantees a visitor at runtime, but it does not cha
 import { createServerFn } from '@tanstack/react-start'
 
 // The datasource id from the table's registration on the application — not the table id.
-const INVOICES = 'e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93'
+const INVOICES = '00000000-0000-0000-0000-000000000001'
 
 const getMyInvoices = createServerFn().handler(async ({ context }) => {
   if (!context.user) throw new Error('Not signed in')
@@ -88,7 +88,7 @@ const getMyInvoices = createServerFn().handler(async ({ context }) => {
 ```tsx
 import { usePermissions } from '@softr/sdk'
 
-const INVOICES = 'e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93' // the registered datasource's id
+const INVOICES = '00000000-0000-0000-0000-000000000001' // the registered datasource's id
 
 function NewInvoiceButton() {
   const { create } = usePermissions(INVOICES)
@@ -107,8 +107,8 @@ Pass an id the visitor's session has no entry for and it throws while rendering,
 declare module '@softr/sdk' {
   interface SoftrUserGroups {
     ids:
-      | 'b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d'
-      | 'f9e8d7c6-5b4a-4938-8271-605f4e3d2c1b'
+      | '00000000-0000-0000-0000-00000000000a'
+      | '00000000-0000-0000-0000-00000000000b'
   }
 }
 export {}
@@ -119,5 +119,5 @@ With this declaration, `user.userGroupIds` and every `userGroupIds` the SDK acce
 ## References
 
 - [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `isAuthorized()` narrows `context.user` while applying the route's rule
-- [reading-records/SKILL.md](../reading-records/SKILL.md): filtering a query by the visitor, and who really authorizes the read
+- [record-queries/SKILL.md](../record-queries/SKILL.md): filtering a query by the visitor, and who really authorizes the read
 - [auth/SKILL.md](../auth/SKILL.md): what changes the value `useCurrentUser` returns

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

@@ -1,15 +1,16 @@
 ---
 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().
+  Call a third-party service connected to the app as an integration:
+  integration.fetch({ dataSourceId, url, method, queryParams, body }) 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, constructing the URL path, and passing
+  query params as an object. Check res.ok before res.json().
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.28
+  library_version: 0.0.29
 ---
 
 **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.
@@ -33,23 +34,28 @@ When the user attaches integrations to the chat, they appear in the `## Attached
 - "Gmail" — database `<databaseId>`, integration `<integrationId>`, type `GMAIL`
 ```
 
-Use `databaseId` as the first argument to `integration.fetch` — that is the `database` coordinate, not the `integration` one. The `integration` value is the OAuth connection identifier; do not pass it 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.
+Use `databaseId` as `dataSourceId` in the options object passed to `integration.fetch` — that is the `database` coordinate, not the `integration` one. The `integration` value is the OAuth connection identifier; do not pass it to `integration.fetch`. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL path and pass query parameters as the `queryParams` object.
 
 ## 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`,
-  )
+  const res = await integration.fetch({
+    dataSourceId: '25d60213-ef4f-4fa0-b094-a46931b2d120',
+    url: 'https://www.googleapis.com/calendar/v3/calendars/primary/events',
+    queryParams: {
+      timeMin: new Date().toISOString(),
+      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 `database` coordinate, not the `integration` one. 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.
+`dataSourceId` is the `databaseId` from the attached data sources section — the `database` coordinate, not the `integration` one. 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
 
@@ -57,21 +63,19 @@ The id (`25d60213-…`) is the `databaseId` from the attached data sources secti
 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 }),
-      },
-    )
+    const res = await integration.fetch({
+      dataSourceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+      url: '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.
+Do not add an `Authorization` key to `headers` — Softr injects the integration's credentials automatically.
 
 ## Base URLs by integration type