@nightfuel-ai/app-sdk 0.1.1 → 0.1.2

package/README.md

@@ -49,6 +49,23 @@ for await (const event of nightfuel.workflows.stream('notify-low-stock', run.run
 }
 ```
 
+## Workflow input
+
+`workflows.run(bindingId, input, { idempotencyKey, customFields })` sends the
+same run input as `workflow_run` in the Nightfuel SDK. `input` is a JSON object
+that reaches the bound workflow's entry node:
+
+- a **Webhook** entry receives it as its request body (`payload.payload.body`),
+  checked against the entry's JSON Schema;
+- a **Request Harness** entry receives it as its input: an App sends `text`
+  only, and `customFields` fills the custom fields the entry declares.
+
+Input that does not match the entry is refused with `400` before the run is
+accepted (`WEBHOOK_BODY_SCHEMA_MISMATCH`, `HARNESS_CUSTOM_FIELDS_INVALID`,
+`WORKFLOW_INPUT_INVALID`). A run accepted with `202` that cannot start (no
+credits, or a workflow that runs with its own published identity) ends its
+stream with `run.failed` and `payload.errorCode`.
+
 ## Runtime environment
 
 A Cloud App receives these variables from the platform; the SDK reads them

package/index.d.ts

@@ -161,10 +161,17 @@ export interface NightfuelDatabaseMutationInput {
 }
 
 export interface NightfuelWorkflowClient {
+  /**
+   * Starts the bound workflow. `input` reaches its entry node: a Request
+   * Harness entry reads it as its input (an App sends `text` only), a Webhook
+   * entry as its request body, checked against the entry's JSON Schema.
+   * `customFields` fills the Request Harness entry's declared custom fields.
+   * Input outside that contract is refused with 400 before the run starts.
+   */
   run(
     bindingId: string,
     input: Record<string, unknown>,
-    options: { idempotencyKey: string }
+    options: { idempotencyKey: string; customFields?: Record<string, unknown> }
   ): Promise<WorkflowRunAccepted>;
   stream<T = NightfuelKnownWorkflowEventData | NightfuelWorkflowEventData>(
     bindingId: string,

package/index.js

@@ -207,7 +207,7 @@ function createNightfuelAppSdk(options = {}) {
         const key = idempotencyKey(options.idempotencyKey);
         return postJson(
           `/internal/hosting/apps/${appId}/workflows/${encodeURIComponent(resolvedBindingId)}/runs`,
-          { input },
+          { input, ...(options.customFields === undefined ? {} : { customFields: options.customFields }) },
           { 'Idempotency-Key': key }
         );
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightfuel-ai/app-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Server-only Nightfuel SDK for a hosted App workload identity.",
   "main": "index.js",
   "types": "index.d.ts",