WIP

ericallam · ericallam · commit c52d986a0d08 · 2024-10-28T14:53:02.000Z
diff --git a/docs/frontend/overview.mdx b/docs/frontend/overview.mdx
@@ -1,7 +1,244 @@
 ---
 title: Overview & Authentication
 sidebarTitle: Overview & Auth
-description: Using the Trigger.dev v3 API from your frontend application.
+description: Using the Trigger.dev SDK from your frontend application.
 ---
 
 Install the preview package: `0.0.0-realtime-20241021152316`.
+
+You can use certain SDK functions in your frontend application to interact with the Trigger.dev API. This guide will show you how to authenticate your requests and use the SDK in your frontend application.
+
+## Authentication
+
+You must authenticate your requests using a "Public Access Token" when using the SDK in your frontend application. To create a Public Access Token, you can use the `auth.createPublicToken` function in your backend code:
+
+```tsx
+const publicToken = await auth.createPublicToken();
+```
+
+To use a Public Access Token in your frontend application, you can call the `auth.configure` function or the `auth.withAuth` function:
+
+```ts
+import { auth } from "@trigger.dev/sdk/v3";
+
+auth.configure({
+  accessToken: publicToken,
+});
+
+// or
+await auth.withAuth({ accessToken: publicToken }, async () => {
+  // Your code here will use the public token
+});
+```
+
+### Scopes
+
+By default a Public Access Token has limited permissions. You can specify the scopes you need when creating a Public Access Token:
+
+```ts
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      runs: true,
+    },
+  },
+});
+```
+
+This will allow the token to read all runs, which is probably not what you want. You can specify only certain runs by passing an array of run IDs:
+
+```ts
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      runs: ["run_1234", "run_5678"],
+    },
+  },
+});
+```
+
+You can scope the token to only read certain tasks:
+
+```ts
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      tasks: ["my-task-1", "my-task-2"],
+    },
+  },
+});
+```
+
+Or tags:
+
+```ts
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      tags: ["my-tag-1", "my-tag-2"],
+    },
+  },
+});
+```
+
+Or a specific batch of runs:
+
+```ts
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      batch: "batch_1234",
+    },
+  },
+});
+```
+
+You can also combine scopes. For example, to read only certain tasks and tags:
+
+```ts
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      tasks: ["my-task-1", "my-task-2"],
+      tags: ["my-tag-1", "my-tag-2"],
+    },
+  },
+});
+```
+
+### Expiration
+
+By default, Public Access Token's expire after 15 minutes. You can specify a different expiration time when creating a Public Access Token:
+
+```ts
+const publicToken = await auth.createPublicToken({
+  expirationTime: "1hr",
+});
+```
+
+- If `expirationTime` is a string, it will be treated as a time span
+- If `expirationTime` is a number, it will be treated as a Unix timestamp
+- If `expirationTime` is a `Date`, it will be treated as a date
+
+The format used for a time span is the same as the [jose package](https://github.com/panva/jose), which is a number followed by a unit. Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year", "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an alias for a year. If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets subtracted from the current unix timestamp. A "from now" suffix can also be used for readability when adding to the current unix timestamp.
+
+## Auto-generated tokens
+
+When triggering a task from your backend, the `handle` received from the `trigger` function now includes a `publicAccessToken` field. This token can be used to authenticate requests in your frontend application:
+
+```ts
+import { tasks } from "@trigger.dev/sdk/v3";
+
+const handle = await tasks.trigger("my-task", { some: "data" });
+
+console.log(handle.publicAccessToken);
+```
+
+By default, tokens returned from the `trigger` function expire after 15 minutes and have a read scope for that specific run, and any tags associated with it. You can customize the expiration of the auto-generated tokens by passing a `publicTokenOptions` object to the `trigger` function:
+
+```ts
+const handle = await tasks.trigger(
+  "my-task",
+  { some: "data" },
+  {
+    tags: ["my-tag"],
+  },
+  {
+    publicAccessToken: {
+      expirationTime: "1hr",
+    },
+  }
+);
+```
+
+You will also get back a Public Access Token when using the `batchTrigger` function:
+
+```ts
+import { tasks } from "@trigger.dev/sdk/v3";
+
+const handle = await tasks.batchTrigger("my-task", [
+  { payload: { some: "data" } },
+  { payload: { some: "data" } },
+  { payload: { some: "data" } },
+]);
+
+console.log(handle.publicAccessToken);
+```
+
+## Available SDK functions
+
+Currently the following functions are available in the frontend SDK:
+
+### runs.retrieve
+
+The `runs.retrieve` function allows you to retrieve a run by its ID.
+
+```ts
+import { runs, auth } from "@trigger.dev/sdk/v3";
+
+// Somewhere in your backend code
+const handle = await tasks.trigger("my-task", { some: "data" });
+
+// In your frontend code
+auth.configure({
+  accessToken: handle.publicAccessToken,
+});
+
+const run = await runs.retrieve(handle.id);
+```
+
+Learn more about the `runs.retrieve` function in the [runs.retrieve doc](/management/runs/retrieve).
+
+### runs.subscribeToRun
+
+The `runs.subscribeToRun` function allows you to subscribe to a run by its ID, and receive updates in real-time when the run changes.
+
+```ts
+import { runs, auth } from "@trigger.dev/sdk/v3";
+
+// Somewhere in your backend code
+const handle = await tasks.trigger("my-task", { some: "data" });
+
+// In your frontend code
+auth.configure({
+  accessToken: handle.publicAccessToken,
+});
+
+for await (const run of runs.subscribeToRun(handle.id)) {
+  // This will log the run every time it changes
+  console.log(run);
+}
+```
+
+See the [Realtime doc](/realtime) for more information.
+
+### runs.subscribeToRunsWithTag
+
+The `runs.subscribeToRunsWithTag` function allows you to subscribe to runs with a specific tag, and receive updates in real-time when the runs change.
+
+```ts
+import { runs, auth } from "@trigger.dev/sdk/v3";
+
+// Somewhere in your backend code
+const handle = await tasks.trigger("my-task", { some: "data" }, { tags: ["my-tag"] });
+
+// In your frontend code
+auth.configure({
+  accessToken: handle.publicAccessToken,
+});
+
+for await (const run of runs.subscribeToRunsWithTag("my-tag")) {
+  // This will log the run every time it changes
+  console.log(run);
+}
+```
+
+See the [Realtime doc](/realtime) for more information.
+
+## React hooks
+
+We also provide React hooks to make it easier to use the SDK in your React application. See our [React hooks](/frontend/react-hooks) documentation for more information.
+
+## Triggering tasks
+
+We don't currently support triggering tasks from the frontend SDK. If this is something you need, please let us know by [upvoting the feature](https://feedback.trigger.dev/p/ability-to-trigger-tasks-from-frontend).
diff --git a/docs/management/overview.mdx b/docs/management/overview.mdx
@@ -50,10 +50,11 @@ main().catch(console.error);
 
 There are two methods of authenticating with the management API: using a secret key associated with a specific environment in a project (`secretKey`), or using a personal access token (`personalAccessToken`). Both methods should only be used in a backend server, as they provide full access to the project.
 
-<Info>
-  Support for client-side authentication is coming soon to v3 but is not available at the time of
-  writing.
-</Info>
+<Note>
+  There is a separate authentication strategy when making requests from your frontend application.
+  See the [Frontend guide](/frontend/overview) for more information. This guide is for backend usage
+  only.
+</Note>
 
 Certain API functions work with both authentication methods, but require different arguments depending on the method used. For example, the `runs.list` function can be called using either a `secretKey` or a `personalAccessToken`, but the `projectRef` argument is required when using a `personalAccessToken`:
 
diff --git a/references/v3-catalog/src/clientUsage.ts b/references/v3-catalog/src/clientUsage.ts
@@ -1,5 +1,5 @@
 import { auth, runs, tasks } from "@trigger.dev/sdk/v3";
-import type { task1, task2 } from "./trigger/taskTypes.js";
+import type { task1, zodTask } from "./trigger/taskTypes.js";
 import { randomUUID } from "crypto";
 
 async function main() {
@@ -22,8 +22,18 @@ async function main() {
 
   console.log("Auto JWT", anyHandle.publicAccessToken);
 
+  const publicToken = await auth.createPublicToken({
+    scopes: {
+      read: {
+        runs: true,
+      },
+    },
+  });
+
   await auth.withAuth({ accessToken: anyHandle.publicAccessToken }, async () => {
-    const subscription = runs.subscribeToRunsWithTag<typeof task1 | typeof task2>(`user:${userId}`);
+    const subscription = runs.subscribeToRunsWithTag<typeof task1 | typeof zodTask>(
+      `user:${userId}`
+    );
 
     for await (const run of subscription) {
       switch (run.taskIdentifier) {
@@ -33,7 +43,7 @@ async function main() {
           console.log("Payload:", run.payload);
           break;
         }
-        case "types/task-2": {
+        case "types/zod": {
           console.log("Run update:", run);
           console.log("Output:", run.output);
           console.log("Payload:", run.payload);
