@requence/task 1.0.0-alpha.5 → 1.0.0-alpha.50

package/CHANGELOG.md

@@ -1,5 +1,275 @@
 # @requence/task
 
+## 1.0.0-alpha.50
+
+### Patch Changes
+
+- 6922266: trace ids
+
+## 1.0.0-alpha.49
+
+### Patch Changes
+
+- c7d1c6b: qos
+
+## 1.0.0-alpha.48
+
+### Minor Changes
+
+- ad9368b: Fix mapped task priority float validation error on backend and add `finalized()` method for cheap task finalization / validation without full progress monitoring.
+
+## 1.0.0-alpha.47
+
+### Patch Changes
+
+- b8d9c18: fix rounding bug for priority
+
+## 1.0.0-alpha.46
+
+### Patch Changes
+
+- eedd227: added task protect endpoint
+
+## 1.0.0-alpha.45
+
+### Patch Changes
+
+- 3a4654c: road to 1.0
+
+## 1.0.0-alpha.44
+
+### Patch Changes
+
+- a57eb9d: correctly define properties
+
+## 1.0.0-alpha.43
+
+### Patch Changes
+
+- d68fa16: don't reject url and response promise when not needed
+
+## 1.0.0-alpha.42
+
+### Patch Changes
+
+- 5dd34ff: there is no type
+
+## 1.0.0-alpha.41
+
+### Patch Changes
+
+- 409cb37: make statusText accessible
+
+## 1.0.0-alpha.40
+
+### Patch Changes
+
+- e0f2d73: recreateTask api
+
+## 1.0.0-alpha.39
+
+### Patch Changes
+
+- 230f9b9: don't reject promises that are not queried
+
+## 1.0.0-alpha.38
+
+### Patch Changes
+
+- bfcb99d: update deployment
+
+## 1.0.0-alpha.37
+
+### Patch Changes
+
+- 574829e: improved task service connection, fixed access token
+
+## 1.0.0-alpha.36
+
+### Patch Changes
+
+- a068600: status should be UPPERCASE
+
+## 1.0.0-alpha.35
+
+### Patch Changes
+
+- 2b0e652: allow task filtering for watch all
+
+## 1.0.0-alpha.34
+
+### Patch Changes
+
+- 8ed981e: linting
+
+## 1.0.0-alpha.33
+
+### Patch Changes
+
+- e4e137b: better auto reconnect
+
+## 1.0.0-alpha.32
+
+### Patch Changes
+
+- c2e0e72: added root task id
+
+## 1.0.0-alpha.31
+
+### Patch Changes
+
+- 4952eff: python types & bug fixes
+
+## 1.0.0-alpha.30
+
+### Patch Changes
+
+- bda4a97: don't use wrong response for error handling
+
+## 1.0.0-alpha.29
+
+### Patch Changes
+
+- e75841f: add missing callbacks
+
+## 1.0.0-alpha.28
+
+### Patch Changes
+
+- f2a63fa: added missing type
+
+## 1.0.0-alpha.27
+
+### Patch Changes
+
+- 63e3195: rerelease task package
+
+## 1.0.0-alpha.26
+
+### Patch Changes
+
+- 14caa43: correctly transport task abort event
+
+## 1.0.0-alpha.25
+
+### Patch Changes
+
+- 0c320ec: added task name and exit name infos
+
+## 1.0.0-alpha.24
+
+### Patch Changes
+
+- 6c441e3: ensure task id gets resolved as early as possible
+
+## 1.0.0-alpha.23
+
+### Patch Changes
+
+- 8743124: fixed type generation & schema resolution
+
+## 1.0.0-alpha.22
+
+### Patch Changes
+
+- 817e7ee: granular data / sub tasks / operator logic
+
+## 1.0.0-alpha.21
+
+### Patch Changes
+
+- bd65a2c: improved logging
+
+## 1.0.0-alpha.20
+
+### Patch Changes
+
+- e83bf22: improve task updates
+
+## 1.0.0-alpha.19
+
+### Patch Changes
+
+- 831c549: added abort reason
+
+## 1.0.0-alpha.18
+
+### Patch Changes
+
+- 3e78516: allow task abort in task package
+
+## 1.0.0-alpha.17
+
+### Patch Changes
+
+- 0a7c05f: include output name in update info
+
+## 1.0.0-alpha.16
+
+### Patch Changes
+
+- 92ef7aa: include node info in all node related task updates
+
+## 1.0.0-alpha.15
+
+### Patch Changes
+
+- 45d26fc: fixed task access token retrieval
+
+## 1.0.0-alpha.14
+
+### Patch Changes
+
+- 3a5e3e2: allow more access token options
+
+## 1.0.0-alpha.13
+
+### Patch Changes
+
+- dc413ab: deps update
+
+## 1.0.0-alpha.12
+
+### Patch Changes
+
+- 77bc2ed: improved task creation and event order
+
+## 1.0.0-alpha.11
+
+### Patch Changes
+
+- 300f7de: temporary upload as formdata
+
+## 1.0.0-alpha.10
+
+### Patch Changes
+
+- 9dcaeae: fixed dependencies
+
+## 1.0.0-alpha.9
+
+### Patch Changes
+
+- 1df3d43: improved typing
+
+## 1.0.0-alpha.8
+
+### Patch Changes
+
+- 679cbaf: streams
+
+## 1.0.0-alpha.7
+
+### Patch Changes
+
+- a464543: improved file matching algorithm
+
+## 1.0.0-alpha.6
+
+### Patch Changes
+
+- 1d847ee: improved files handling
+
 ## 1.0.0-alpha.5
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,383 @@
+# @requence/task
+
+This package lets you start and monitor Requence tasks programmatically from a TypeScript / Bun application.
+
+## Installation
+
+```bash
+npm install @requence/task
+```
+
+## Authentication
+
+Every call to `createTask` requires an **access token** — either a personal access token or a scoped token created at the organization, group, or project level.
+
+The token is resolved in this order:
+
+1. `accessToken` option passed to `createTask()`
+2. `REQUENCE_TASK_ACCESS_TOKEN` or `REQUENCE_ACCESS_TOKEN` environment variable
+3. `requence.task.accessToken` or `requence.accessToken` in `package.json`
+
+```bash
+REQUENCE_ACCESS_TOKEN=your-token bun run index.ts
+```
+
+## Basic Usage
+
+```typescript
+import { createTask } from '@requence/task'
+
+const result = await createTask({
+  taskTemplate: 'my-template',
+  input: { name: 'World' },
+})
+
+console.log(result.result) // The final output of the task
+```
+
+> **Note:** `await createTask(...)` waits for the **entire task** to finish. If you don't need to block, omit the `await` and use the returned task handle instead.
+
+## Task Handle
+
+`createTask` returns a **task handle** immediately. You can use it to access task metadata without waiting for the task to complete:
+
+```typescript
+const task = createTask({ taskTemplate: 'my-template', input: {} })
+
+const taskId = await task.getTaskId()   // Resolves as soon as the task is created
+const taskUrl = await task.getTaskUrl() // URL to view the task in the Requence UI
+
+await task.abort('No longer needed')    // Abort the running task
+await task.protect()                    // Protect the task from automatic cleanup
+
+// Await the final result when you need it
+const result = await task
+```
+
+The task handle is also an **AsyncIterable** — iterate over it to stream updates as the task executes.
+
+### Awaiting Finalization (Cheap Monitoring)
+
+By default, awaiting the result or iterating the handle starts full SSE monitoring. If you only need to confirm that the task passed input validation and started on the backend — without tracking every node — await `task.finalized()`:
+
+```typescript
+const task = createTask({ taskTemplate: 'my-template', input: { /* ... */ } })
+
+try {
+  const taskId = await task.finalized()
+  console.log(`Task ${taskId} is running in the background`)
+} catch (error) {
+  console.error('Validation failed:', error.message)
+}
+```
+
+`finalized()` resolves with the task ID on success, or rejects with a `TaskError` if the task cannot be created (e.g. schema validation failure).
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `taskTemplate` | `string` | — | **Required.** Name of the task template |
+| `input` | `unknown` | — | Required when the template defines an input schema |
+| `name` | `string` | — | Human-readable task name shown in the UI |
+| `priority` | `number` | `2` | Priority `0` (lowest) to `4` (highest) |
+| `accessToken` | `string` | — | Access token (falls back to env / config file) |
+| `requireAck` | `boolean` | `false` | Enable delivery guarantee (see below) |
+| `suppressBranchWarning` | `boolean` | `false` | Suppress the branch warning when running on a non-live branch |
+
+## Result
+
+When awaited, the task handle resolves to a result object:
+
+```typescript
+const result = await createTask({ taskTemplate: 'my-template', input: {} })
+
+result.input            // The input you provided
+result.result           // The final task output
+result.taskId           // Unique task identifier
+result.taskUrl          // URL to view the task in the Requence UI
+result.getNodeData(alias)  // Get output from a specific node by alias
+result.getNodeError(alias) // Get error from a specific node by alias
+```
+
+## Streaming Updates
+
+The task handle is an `AsyncIterable` that emits updates as the task executes. Iterate over it with `for await`:
+
+```typescript
+const task = createTask({
+  taskTemplate: 'my-template',
+  input: { data: [1, 2, 3] },
+})
+
+for await (const update of task) {
+  switch (update.type) {
+    case 'taskStart':
+      console.log(`Task ${update.taskId} started`)
+      break
+    case 'nodeStart':
+      console.log(`Node ${update.node.alias ?? update.node.id} started`)
+      break
+    case 'nodeUpdate':
+      console.log(`Node output:`, update.data)
+      break
+    case 'nodeError':
+      console.log(`Node error:`, update.error)
+      break
+    case 'nodeDefer':
+      console.log(`Node deferred:`, update.reason)
+      break
+    case 'nodeEnd':
+      console.log(`Node ${update.node.alias ?? update.node.id} finished`)
+      break
+    case 'taskEnd':
+      console.log(`Task completed:`, update.context.result)
+      break
+    case 'taskError':
+      console.log(`Task failed:`, update.reason)
+      break
+    case 'taskAborted':
+      console.log(`Task aborted:`, update.reason)
+      break
+  }
+}
+```
+
+### `onUpdate` callback
+
+Alternatively, pass a callback as the second argument to stream updates while still awaiting the final result:
+
+```typescript
+const result = await createTask(
+  { taskTemplate: 'my-template', input: {} },
+  (update) => {
+    console.log(`[${update.type}]`, update.timestamp)
+  },
+)
+```
+
+### Update types
+
+| Type | Description |
+|---|---|
+| `taskStart` | Task execution has begun. Contains `input` and `taskId`. |
+| `nodeStart` | A node started processing. Contains `node` info (id, type, alias). |
+| `nodeUpdate` | A node produced output. Contains `data` and `output` (named output, if any). |
+| `nodeError` | A node encountered an error. Contains `error` message. |
+| `nodeDefer` | A node has been deferred (waiting for an external callback). |
+| `nodeEnd` | A node finished processing. |
+| `taskEnd` | The task completed successfully. Contains final `result`. |
+| `taskError` | The task failed. Contains `reason`. |
+| `taskAborted` | The task was aborted. Contains `reason`. |
+
+### Context on every update
+
+Every update includes a `context` object with the current accumulated state:
+
+```typescript
+update.context.input                  // The task input
+update.context.taskId                 // The task ID
+update.context.result                 // Accumulated result (partial until taskEnd)
+update.context.getNodeData(alias)     // Output from a specific node by alias
+update.context.getNodeError(alias)    // Error from a specific node by alias
+```
+
+## Aborting a Task
+
+Via the task handle:
+
+```typescript
+const task = createTask({ taskTemplate: 'my-template', input: {} })
+await task.abort('No longer needed')
+```
+
+Or standalone, using a known task ID:
+
+```typescript
+import { abortTask } from '@requence/task'
+
+await abortTask({
+  taskId: 'some-task-id',
+  reason: 'Cancelled by user',
+})
+```
+
+## Protecting a Task
+
+Protected tasks are excluded from automatic cleanup — useful for important results you want to keep indefinitely.
+
+Via the task handle:
+
+```typescript
+const task = createTask({ taskTemplate: 'my-template', input: {} })
+await task.protect()
+```
+
+Or standalone:
+
+```typescript
+import { protectTask } from '@requence/task'
+
+await protectTask({ taskId: 'some-task-id' })
+```
+
+## Fetching a Task by ID
+
+Retrieve the current state of any task:
+
+```typescript
+import { getTask } from '@requence/task'
+
+const task = await getTask('some-task-id')
+// or: getTask({ taskId: 'some-task-id', accessToken: '...' })
+
+task.status        // 'SUCCESSFUL' | 'FAILED' | 'IDLE' | 'PENDING' | 'RUNNING' | 'STOPPED' | 'AWAITING_DELIVERY'
+task.statusText    // Human-readable status description, if any
+task.taskTemplate  // The task template name
+task.name          // Human-readable task name
+task.branch        // 'live' or a branch name
+
+task.context.input                 // The task's input
+task.context.result                // The task's result (if finished)
+task.context.getNodeData(alias)    // Output from a specific node
+task.context.getNodeError(alias)   // Error from a specific node
+```
+
+## Recreating a Task
+
+Re-run an existing task with the same template and input:
+
+```typescript
+import { recreateTask } from '@requence/task'
+
+const task = await recreateTask({
+  taskId: 'some-task-id',
+  name: 'My Retry',      // Optional — overrides the original name
+  priority: 3,           // Optional — overrides the original priority
+})
+
+const result = await task
+```
+
+## Watching All Tasks (`watchTasks`)
+
+Subscribe to real-time updates across **all tasks** — useful for dashboards, monitoring systems, or audit logs.
+
+```typescript
+import { watchTasks } from '@requence/task'
+
+const stop = watchTasks({
+  since: new Date(),
+  onUpdate(update) {
+    console.log(`[${update.type}] Task ${update.context.taskId}`)
+  },
+})
+
+// Later — disconnect the watcher
+stop()
+```
+
+`watchTasks` returns a stop function that is also an **AsyncIterable**:
+
+```typescript
+const watcher = watchTasks({ since: new Date() })
+
+for await (const update of watcher) {
+  console.log(update.type, update.context.taskId)
+
+  if (shouldStop) {
+    watcher() // stop watching
+    break
+  }
+}
+```
+
+### `watchTasks` options
+
+| Option | Type | Description |
+|---|---|---|
+| `since` | `Date` | **Required.** Only receive updates after this timestamp. |
+| `accessToken` | `string` | Access token (falls back to env / config file) |
+| `filter.only` | `string[]` | Filter to specific update types (e.g. `['taskEnd', 'taskError']`) |
+| `onUpdate` | `function` | Callback for each update |
+| `onConnect` | `function` | Called when the connection is established |
+| `onReconnecting` | `function` | Called when the connection is being re-established |
+| `onError` | `function` | Called on connection errors — receives `(status, reason)` |
+
+### Incomplete updates
+
+Each update from `watchTasks` includes an `incomplete` flag. When `true`, it means the watcher connected after the task had already started and the `taskStart` event was missed. Use this to decide whether to skip or partially process the update.
+
+It also includes a `rootTaskId` field — the ID of the root task when the update belongs to a sub-task, or `null` for top-level tasks.
+
+## Delivery Guarantee
+
+By default, a task transitions immediately from `RUNNING` to `SUCCESSFUL` / `FAILED` / `STOPPED` when it finishes. If the process that started the task crashes at the exact moment the terminal event is emitted, the event can be lost.
+
+Setting `requireAck: true` enables an explicit acknowledgement step:
+
+1. When the task reaches its terminal state the backend holds it in **`AWAITING_DELIVERY`** instead of immediately finalising.
+2. The SDK receives the terminal event over SSE and automatically sends an ACK back.
+3. Only after the ACK is received does the task move to its real final status, and the exact delivery timestamp is recorded.
+
+```typescript
+const result = await createTask({
+  taskTemplate: 'my-template',
+  input: { /* ... */ },
+  requireAck: true,
+})
+// Resolves only after the ACK has been confirmed
+```
+
+`requireAck` also works with `watchTasks` — when a task with `requireAck` reaches its terminal state, the watcher ACKs it automatically using the same access token.
+
+## CLI — Generate Types
+
+The package ships with a CLI that generates TypeScript types for your task templates, derived from the schemas defined in the Requence UI:
+
+```bash
+npx requence-task generate-types
+```
+
+This creates a `requence-env.d.ts` file in your project root. TypeScript picks it up automatically — `input`, `result`, and node data will be fully typed.
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `--access-token` | — | Access token (falls back to env / config file) |
+| `--outfile` | `requence-env.d.ts` | Name of the generated type file |
+| `--outdir` | `.` | Directory to write the type file to |
+
+The token resolution order for the CLI is the same as for `createTask`: option → `REQUENCE_TASK_ACCESS_TOKEN` / `REQUENCE_ACCESS_TOKEN` env var → `requence.task.accessToken` / `requence.accessToken` in `package.json`.
+
+## Full Example
+
+```typescript
+import { createTask, watchTasks } from '@requence/task'
+
+// Start a task and stream its progress
+const task = createTask(
+  {
+    taskTemplate: 'invoice-processing',
+    input: { invoiceUrl: 'https://...' },
+    name: 'Invoice #1234',
+    priority: 3,
+  },
+  (update) => {
+    if (update.type === 'nodeUpdate') {
+      console.log('Node result:', update.data)
+    }
+  },
+)
+
+const taskId = await task.getTaskId()
+console.log('Started task:', taskId)
+
+try {
+  const result = await task
+  console.log('Final result:', result.result)
+} catch (error) {
+  console.error('Task failed:', error.message)
+}
+```

package/build/chunk-b4h2we9a.js

@@ -0,0 +1,35 @@
+// ../helpers/src/utils/obfuscate.ts
+var separator = "";
+var base65Chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+-$";
+var base65CharToIndex = {};
+for (let i = 0;i < base65Chars.length; i++) {
+  base65CharToIndex[base65Chars[i]] = i;
+}
+function deobfuscate(str) {
+  const paddingCount = parseInt(str.slice(-1), 10);
+  str = str.slice(0, -1);
+  let binaryString = "";
+  for (let i = 0;i < str.length; i++) {
+    const decimalValue = base65CharToIndex[str[i]];
+    const binaryChunk = decimalValue.toString(2).padStart(6, "0");
+    binaryString += binaryChunk;
+  }
+  if (paddingCount > 0) {
+    binaryString = binaryString.slice(0, -paddingCount);
+  }
+  let decodedString = "";
+  const charSize = 16;
+  for (let i = 0;i < binaryString.length; i += charSize) {
+    const byte = binaryString.substring(i, i + charSize);
+    if (byte.length === 16) {
+      const charCode = parseInt(byte, 2);
+      decodedString += String.fromCharCode(charCode);
+    }
+  }
+  return decodedString.split(separator);
+}
+
+export { deobfuscate };
+
+//# debugId=58DA2BE245CFC84464756E2164756E21
+//# sourceMappingURL=chunk-b4h2we9a.js.map

package/build/chunk-b4h2we9a.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../helpers/src/utils/obfuscate.ts"],
+  "sourcesContent": [
+    "const separator = '\\u{f6ee}'\n\nconst base65Chars =\n  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+-$'\n\nconst base65CharToIndex: Record<string, number> = {}\nfor (let i = 0; i < base65Chars.length; i++) {\n  base65CharToIndex[base65Chars[i]] = i\n}\n\nexport function obfuscate(...parts: Array<string>) {\n  const str = parts.join(separator)\n  let binaryString = ''\n\n  for (let i = 0; i < str.length; i++) {\n    const charCode = str.charCodeAt(i)\n    binaryString += charCode.toString(2).padStart(16, '0')\n  }\n\n  let encodedString = ''\n  const chunkSize = 6\n  let paddingCount = 0\n\n  for (let i = 0; i < binaryString.length; i += chunkSize) {\n    let chunk = binaryString.substring(i, i + chunkSize)\n\n    if (chunk.length < chunkSize) {\n      paddingCount = chunkSize - chunk.length\n      chunk = chunk.padEnd(chunkSize, '0')\n    }\n\n    const decimalValue = parseInt(chunk, 2)\n    encodedString += base65Chars[decimalValue]\n  }\n\n  return encodedString + paddingCount.toString()\n}\n\nexport function randomString(length: number) {\n  const randomValues = new Uint8Array(length)\n  crypto.getRandomValues(randomValues)\n\n  let randomString = ''\n  for (let i = 0; i < length; i++) {\n    randomString += base65Chars[randomValues[i] % base65Chars.length]\n  }\n\n  return randomString\n}\n\nexport function deobfuscate(str: string) {\n  const paddingCount = parseInt(str.slice(-1), 10)\n  str = str.slice(0, -1)\n\n  let binaryString = ''\n\n  for (let i = 0; i < str.length; i++) {\n    const decimalValue = base65CharToIndex[str[i]]\n    const binaryChunk = decimalValue.toString(2).padStart(6, '0')\n    binaryString += binaryChunk\n  }\n\n  if (paddingCount > 0) {\n    binaryString = binaryString.slice(0, -paddingCount)\n  }\n\n  let decodedString = ''\n  const charSize = 16\n\n  for (let i = 0; i < binaryString.length; i += charSize) {\n    const byte = binaryString.substring(i, i + charSize)\n    if (byte.length === 16) {\n      const charCode = parseInt(byte, 2)\n      decodedString += String.fromCharCode(charCode)\n    }\n  }\n\n  return decodedString.split(separator)\n}\n"
+  ],
+  "mappings": ";AAAA,IAAM,YAAY;AAElB,IAAM,cACJ;AAEF,IAAM,oBAA4C,CAAC;AACnD,SAAS,IAAI,EAAG,IAAI,YAAY,QAAQ,KAAK;AAAA,EAC3C,kBAAkB,YAAY,MAAM;AACtC;AA0CO,SAAS,WAAW,CAAC,KAAa;AAAA,EACvC,MAAM,eAAe,SAAS,IAAI,MAAM,EAAE,GAAG,EAAE;AAAA,EAC/C,MAAM,IAAI,MAAM,GAAG,EAAE;AAAA,EAErB,IAAI,eAAe;AAAA,EAEnB,SAAS,IAAI,EAAG,IAAI,IAAI,QAAQ,KAAK;AAAA,IACnC,MAAM,eAAe,kBAAkB,IAAI;AAAA,IAC3C,MAAM,cAAc,aAAa,SAAS,CAAC,EAAE,SAAS,GAAG,GAAG;AAAA,IAC5D,gBAAgB;AAAA,EAClB;AAAA,EAEA,IAAI,eAAe,GAAG;AAAA,IACpB,eAAe,aAAa,MAAM,IAAI,YAAY;AAAA,EACpD;AAAA,EAEA,IAAI,gBAAgB;AAAA,EACpB,MAAM,WAAW;AAAA,EAEjB,SAAS,IAAI,EAAG,IAAI,aAAa,QAAQ,KAAK,UAAU;AAAA,IACtD,MAAM,OAAO,aAAa,UAAU,GAAG,IAAI,QAAQ;AAAA,IACnD,IAAI,KAAK,WAAW,IAAI;AAAA,MACtB,MAAM,WAAW,SAAS,MAAM,CAAC;AAAA,MACjC,iBAAiB,OAAO,aAAa,QAAQ;AAAA,IAC/C;AAAA,EACF;AAAA,EAEA,OAAO,cAAc,MAAM,SAAS;AAAA;",
+  "debugId": "58DA2BE245CFC84464756E2164756E21",
+  "names": []
+}