@rawdash/sdk-nextjs 0.15.0

package/README.md

@@ -0,0 +1,104 @@
+# @rawdash/sdk-nextjs
+
+[![npm version](https://img.shields.io/npm/v/@rawdash/sdk-nextjs)](https://www.npmjs.com/package/@rawdash/sdk-nextjs)
+[![license](https://img.shields.io/npm/l/@rawdash/sdk-nextjs)](https://github.com/rawdash/rawdash/blob/main/LICENSE)
+
+Rawdash SDK for the Next.js App Router.
+
+## What it is
+
+`@rawdash/sdk-nextjs` extends `@rawdash/sdk-client` with Next.js-specific behavior: the `http` function tags widget requests with Next.js cache tags so they can be invalidated via `revalidateTag`, and `createRawdashClient` wraps a data source so `triggerSync` automatically revalidates widget data in Server Components after the sync completes.
+
+Use this package when your rawdash server runs separately from your Next.js app. For an in-process setup (engine in the same Next.js process), use `@rawdash/sdk-client`'s `inProcess` directly.
+
+## Install
+
+```sh
+npm install @rawdash/sdk-nextjs
+```
+
+Requires Next.js 14+.
+
+## Quick example
+
+```ts
+// lib/rawdash.ts
+import { createRawdashClient, http } from '@rawdash/sdk-nextjs';
+
+export const rawdash = createRawdashClient(
+  http({
+    baseUrl: process.env.RAWDASH_URL!,
+    apiKey: process.env.RAWDASH_API_KEY,
+  }),
+);
+```
+
+```tsx
+// app/dashboard/page.tsx
+import { rawdash } from '@/lib/rawdash';
+
+export default async function DashboardPage() {
+  const widgets = await rawdash.getWidgets('engineering');
+
+  return (
+    <div>
+      {widgets.map((w) => (
+        <div key={w.id}>{/* render widget */}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+In `app/actions.ts`:
+
+```ts
+'use server';
+
+import { rawdash } from '@/lib/rawdash';
+
+export async function syncDashboard() {
+  // Triggers sync, polls /sync/state until it settles (succeeded or failed),
+  // then calls revalidateTag('rawdash') so the Server Components re-fetch
+  // widget data on next request. Throws on sync failure.
+  await rawdash.triggerSync();
+}
+```
+
+> **Don't block SSR on a sync.** `triggerSync` (and `ensureFresh`) wait for the sync to settle, which can take up to ~30s. Calling either from a Server Component would block every page render. Use them in Server Actions, cron-triggered routes, or webhooks — and let pages render against whatever's cached.
+
+## Switching between in-process and HTTP
+
+```ts
+// lib/rawdash.ts
+import { inProcess } from '@rawdash/sdk-client';
+import { createRawdashClient } from '@rawdash/sdk-nextjs';
+import { http } from '@rawdash/sdk-nextjs';
+
+const source =
+  process.env.NODE_ENV === 'production'
+    ? http({ baseUrl: process.env.RAWDASH_URL! })
+    : inProcess(localEngine);
+
+export const rawdash = createRawdashClient(source);
+```
+
+## API
+
+### `http(options): DataSource`
+
+Next.js-aware variant of `http` from `@rawdash/sdk-client`. Adds the `'rawdash'` cache tag to all widget fetch requests so they can be invalidated with `revalidateTag('rawdash')`. Accepts the same options as `@rawdash/sdk-client`'s `http`.
+
+### `createRawdashClient(dataSource): DataSource`
+
+Wraps any `DataSource` with Next.js behavior: `triggerSync` polls `/sync/state` until the sync settles (transitions to `succeeded` or `failed`), then calls `revalidateTag('rawdash')` to bust Server Component caches. Throws on `failed` or if the sync doesn't settle within 30s. `ensureFresh` is also tagged to revalidate after a sync. All other methods are passed through unchanged.
+
+## Links
+
+- [rawdash docs](https://rawdash.dev)
+- [GitHub](https://github.com/rawdash/rawdash)
+- [Issues](https://github.com/rawdash/rawdash/issues)
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { DataSource } from '@rawdash/core';
+export { ACTIVE_SYNC_STATUSES, CachedWidget, DataSource, HealthResponse, SyncState, SyncStatus, TriggerSyncResponse, WidgetSyncState, WidgetsListResponse, isSyncActive } from '@rawdash/core';
+import { HttpOptions } from '@rawdash/sdk-client';
+export { HttpOptions } from '@rawdash/sdk-client';
+
+/**
+ * Next.js-aware variant of `http` from `@rawdash/sdk-client`.
+ *
+ * Identical to `http` but wraps the underlying fetch so that widget requests
+ * are tagged with the `'rawdash'` cache tag, enabling `revalidateTag`-based
+ * invalidation from Server Actions.
+ */
+declare function http(opts: HttpOptions): DataSource;
+declare function createRawdashClient(dataSource: DataSource): DataSource;
+
+export { createRawdashClient, http };

package/dist/index.js

@@ -0,0 +1,72 @@
+// src/index.ts
+import { isSyncActive } from "@rawdash/core";
+import { http as clientHttp } from "@rawdash/sdk-client";
+import { revalidateTag } from "next/cache";
+import { ACTIVE_SYNC_STATUSES, isSyncActive as isSyncActive2 } from "@rawdash/core";
+var RAWDASH_CACHE_TAG = "rawdash";
+function http(opts) {
+  const taggedFetch = (input, init) => {
+    return globalThis.fetch(
+      input,
+      {
+        ...init,
+        next: {
+          ...init?.next,
+          tags: [
+            ...init?.next?.tags ?? [],
+            RAWDASH_CACHE_TAG
+          ]
+        }
+      }
+    );
+  };
+  return clientHttp({ ...opts, fetch: taggedFetch });
+}
+var DEFAULT_SYNC_TIMEOUT_MS = 3e4;
+var DEFAULT_SYNC_POLL_INTERVAL_MS = 500;
+function createRawdashClient(dataSource) {
+  return {
+    getWidget: (dashboardId, widgetId) => dataSource.getWidget(dashboardId, widgetId),
+    getWidgets: (dashboardId) => dataSource.getWidgets(dashboardId),
+    getHealth: () => dataSource.getHealth(),
+    getSyncState: () => dataSource.getSyncState(),
+    async ensureFresh(maxAgeMs) {
+      const synced = await dataSource.ensureFresh(maxAgeMs);
+      if (synced) {
+        revalidateTag(RAWDASH_CACHE_TAG);
+      }
+      return synced;
+    },
+    async triggerSync() {
+      const result = await dataSource.triggerSync();
+      const deadline = Date.now() + DEFAULT_SYNC_TIMEOUT_MS;
+      for (; ; ) {
+        const state = await dataSource.getSyncState();
+        if (!isSyncActive(state.status)) {
+          if (state.status === "failed") {
+            throw new Error(
+              `Rawdash sync failed: ${state.lastError ?? "unknown error"}`
+            );
+          }
+          revalidateTag(RAWDASH_CACHE_TAG);
+          return result;
+        }
+        if (Date.now() >= deadline) {
+          throw new Error(
+            `Rawdash sync did not settle within ${DEFAULT_SYNC_TIMEOUT_MS}ms (last status: ${state.status})`
+          );
+        }
+        await new Promise(
+          (resolve) => setTimeout(resolve, DEFAULT_SYNC_POLL_INTERVAL_MS)
+        );
+      }
+    }
+  };
+}
+export {
+  ACTIVE_SYNC_STATUSES,
+  createRawdashClient,
+  http,
+  isSyncActive2 as isSyncActive
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { DataSource } from '@rawdash/core';\n\n/**\n * A configured Rawdash client for use in Next.js Server Components and Server\n * Actions.\n *\n * Wrap a `DataSource` (from `@rawdash/core`) with Next.js-specific\n * behaviour: `triggerSync` waits for the sync to complete, then calls\n * `revalidateTag` so Server Components re-fetch widget data.\n *\n * ```ts\n * // lib/rawdash.ts\n * import { createRawdashClient, http } from '@rawdash/sdk-nextjs';\n *\n * export const rawdash = createRawdashClient(\n *   http({ baseUrl: process.env.RAWDASH_URL! }),\n * );\n * ```\n */\nimport { isSyncActive } from '@rawdash/core';\nimport { http as clientHttp } from '@rawdash/sdk-client';\nimport type { HttpOptions } from '@rawdash/sdk-client';\nimport { revalidateTag } from 'next/cache';\n\nexport type { HttpOptions } from '@rawdash/sdk-client';\n\nexport type {\n  CachedWidget,\n  DataSource,\n  HealthResponse,\n  SyncState,\n  SyncStatus,\n  TriggerSyncResponse,\n  WidgetSyncState,\n  WidgetsListResponse,\n} from '@rawdash/core';\n\nexport { ACTIVE_SYNC_STATUSES, isSyncActive } from '@rawdash/core';\n\nconst RAWDASH_CACHE_TAG = 'rawdash';\n\ntype NextFetchInit = RequestInit & {\n  next?: {\n    revalidate?: number | false;\n    tags?: string[];\n  };\n};\n\n/**\n * Next.js-aware variant of `http` from `@rawdash/sdk-client`.\n *\n * Identical to `http` but wraps the underlying fetch so that widget requests\n * are tagged with the `'rawdash'` cache tag, enabling `revalidateTag`-based\n * invalidation from Server Actions.\n */\nexport function http(opts: HttpOptions): DataSource {\n  const taggedFetch: typeof globalThis.fetch = (input, init) => {\n    return globalThis.fetch(\n      input as RequestInfo,\n      {\n        ...(init as NextFetchInit),\n        next: {\n          ...(init as NextFetchInit | undefined)?.next,\n          tags: [\n            ...((init as NextFetchInit | undefined)?.next?.tags ?? []),\n            RAWDASH_CACHE_TAG,\n          ],\n        },\n      } as RequestInit,\n    );\n  };\n  return clientHttp({ ...opts, fetch: taggedFetch });\n}\n\nconst DEFAULT_SYNC_TIMEOUT_MS = 30_000;\nconst DEFAULT_SYNC_POLL_INTERVAL_MS = 500;\n\nexport function createRawdashClient(dataSource: DataSource): DataSource {\n  return {\n    getWidget: (dashboardId, widgetId) =>\n      dataSource.getWidget(dashboardId, widgetId),\n\n    getWidgets: (dashboardId) => dataSource.getWidgets(dashboardId),\n\n    getHealth: () => dataSource.getHealth(),\n\n    getSyncState: () => dataSource.getSyncState(),\n\n    async ensureFresh(maxAgeMs) {\n      const synced = await dataSource.ensureFresh(maxAgeMs);\n      if (synced) {\n        revalidateTag(RAWDASH_CACHE_TAG);\n      }\n      return synced;\n    },\n\n    async triggerSync() {\n      const result = await dataSource.triggerSync();\n\n      const deadline = Date.now() + DEFAULT_SYNC_TIMEOUT_MS;\n      for (;;) {\n        const state = await dataSource.getSyncState();\n        if (!isSyncActive(state.status)) {\n          if (state.status === 'failed') {\n            throw new Error(\n              `Rawdash sync failed: ${state.lastError ?? 'unknown error'}`,\n            );\n          }\n          revalidateTag(RAWDASH_CACHE_TAG);\n          return result;\n        }\n        if (Date.now() >= deadline) {\n          throw new Error(\n            `Rawdash sync did not settle within ${DEFAULT_SYNC_TIMEOUT_MS}ms (last status: ${state.status})`,\n          );\n        }\n        await new Promise<void>((resolve) =>\n          setTimeout(resolve, DEFAULT_SYNC_POLL_INTERVAL_MS),\n        );\n      }\n    },\n  };\n}\n"],"mappings":";AAmBA,SAAS,oBAAoB;AAC7B,SAAS,QAAQ,kBAAkB;AAEnC,SAAS,qBAAqB;AAe9B,SAAS,sBAAsB,gBAAAA,qBAAoB;AAEnD,IAAM,oBAAoB;AAgBnB,SAAS,KAAK,MAA+B;AAClD,QAAM,cAAuC,CAAC,OAAO,SAAS;AAC5D,WAAO,WAAW;AAAA,MAChB;AAAA,MACA;AAAA,QACE,GAAI;AAAA,QACJ,MAAM;AAAA,UACJ,GAAI,MAAoC;AAAA,UACxC,MAAM;AAAA,YACJ,GAAK,MAAoC,MAAM,QAAQ,CAAC;AAAA,YACxD;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACA,SAAO,WAAW,EAAE,GAAG,MAAM,OAAO,YAAY,CAAC;AACnD;AAEA,IAAM,0BAA0B;AAChC,IAAM,gCAAgC;AAE/B,SAAS,oBAAoB,YAAoC;AACtE,SAAO;AAAA,IACL,WAAW,CAAC,aAAa,aACvB,WAAW,UAAU,aAAa,QAAQ;AAAA,IAE5C,YAAY,CAAC,gBAAgB,WAAW,WAAW,WAAW;AAAA,IAE9D,WAAW,MAAM,WAAW,UAAU;AAAA,IAEtC,cAAc,MAAM,WAAW,aAAa;AAAA,IAE5C,MAAM,YAAY,UAAU;AAC1B,YAAM,SAAS,MAAM,WAAW,YAAY,QAAQ;AACpD,UAAI,QAAQ;AACV,sBAAc,iBAAiB;AAAA,MACjC;AACA,aAAO;AAAA,IACT;AAAA,IAEA,MAAM,cAAc;AAClB,YAAM,SAAS,MAAM,WAAW,YAAY;AAE5C,YAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,iBAAS;AACP,cAAM,QAAQ,MAAM,WAAW,aAAa;AAC5C,YAAI,CAAC,aAAa,MAAM,MAAM,GAAG;AAC/B,cAAI,MAAM,WAAW,UAAU;AAC7B,kBAAM,IAAI;AAAA,cACR,wBAAwB,MAAM,aAAa,eAAe;AAAA,YAC5D;AAAA,UACF;AACA,wBAAc,iBAAiB;AAC/B,iBAAO;AAAA,QACT;AACA,YAAI,KAAK,IAAI,KAAK,UAAU;AAC1B,gBAAM,IAAI;AAAA,YACR,sCAAsC,uBAAuB,oBAAoB,MAAM,MAAM;AAAA,UAC/F;AAAA,QACF;AACA,cAAM,IAAI;AAAA,UAAc,CAAC,YACvB,WAAW,SAAS,6BAA6B;AAAA,QACnD;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":["isSyncActive"]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@rawdash/sdk-nextjs",
+  "version": "0.15.0",
+  "description": "Rawdash client SDK for Next.js App Router (Server Components and Server Actions)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rawdash/rawdash.git",
+    "directory": "packages/sdk-nextjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "@rawdash/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@rawdash/sdk-client": "workspace:*",
+    "@rawdash/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "next": ">=14.0.0"
+  },
+  "devDependencies": {
+    "next": "^15.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.2"
+  }
+}