docs: realtime, react hooks, and frontend usage (#1434)

* WIP realtime/frontend docs

* WIP

* Deleted old examples

* Improved styling

* Improved the generated example styles

* More style improvements

* More realtime docs

* Couple doc tweeks

* runs-and-attempts -> runs

* Remove the prerelease package version

---------

Co-authored-by: James Ritchie <[email protected]>

Author: ericallam

docs/frontend/overview.mdx

@@ -0,0 +1,242 @@
+---
+title: Overview & Authentication
+sidebarTitle: Overview & Auth
+description: Using the Trigger.dev SDK from your frontend application.
+---
+
+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).