@nightfuel-ai/app-sdk 0.1.0 → 0.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 NightFUEL
+Copyright (c) 2026 Nightfuel
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,7 @@
 # @nightfuel-ai/app-sdk
 
-`@nightfuel-ai/app-sdk` is for the **server process of a NightFUEL Cloud App**.
-It uses the App's Cloud Run workload identity to reach the private NightFUEL
+`@nightfuel-ai/app-sdk` is for the **server process of a Nightfuel Cloud App**.
+It uses the App's Cloud Run workload identity to reach the private Nightfuel
 App gateway. It has no browser build and must never be placed in client code.
 
 ```bash
@@ -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
@@ -78,7 +95,7 @@ its machine-readable stream code and `afterSeq`. Persist `data.seq` after the
 App has committed its own effect when process-restart recovery matters; SSE is
 at-least-once, not exactly-once.
 
-## Calls from NightFUEL into the App
+## Calls from Nightfuel into the App
 
 The Apphook workflow node signs each request it sends to the App in the
 `X-NF-App-Call` header. `verifyNightfuelCall` checks the signature, expiry,

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,
@@ -182,7 +189,7 @@ export interface NightfuelAppSdk {
 
 export function createNightfuelAppSdk(options?: NightfuelAppSdkOptions): NightfuelAppSdk;
 
-/** The claims NightFUEL signs into an Apphook request. */
+/** The claims Nightfuel signs into an Apphook request. */
 export interface NightfuelCallClaims {
   v: 1;
   appId: string;
@@ -199,7 +206,7 @@ export interface NightfuelCallClaims {
 }
 
 /**
- * Verifies a call NightFUEL made to this App and returns its claims.
+ * Verifies a call Nightfuel made to this App and returns its claims.
  * `rawBody` is the JSON body, or the multipart `payload` field, exactly as
  * received -- parse it only after this returns. Pure: no network, no platform
  * identity, so an App can prove it rejects a forged call in a unit test.

package/index.js

@@ -4,7 +4,7 @@
 //
 // This package intentionally has no browser build. It authenticates with the
 // Google metadata server available to the App's Cloud Run service account and
-// calls only pre-bound NightFUEL App runtime endpoints.
+// calls only pre-bound Nightfuel App runtime endpoints.
 
 const crypto = require('crypto');
 const { parseSseFrame, recoverableSseStream, terminalRunStatus } = require('./stream');
@@ -168,7 +168,7 @@ function createNightfuelAppSdk(options = {}) {
     if (!response.ok && !allowErrorResponse) {
       const payload = await responsePayload(response);
       throw new NightfuelAppSdkError(
-        payload?.error || `NightFUEL App gateway request failed (${response.status})`,
+        payload?.error || `Nightfuel App gateway request failed (${response.status})`,
         { status: response.status, code: payload?.code || 'NIGHTFUEL_APP_SDK_GATEWAY_ERROR', payload }
       );
     }
@@ -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 }
         );
       },
@@ -249,7 +249,7 @@ function createNightfuelAppSdk(options = {}) {
   });
 }
 
-// ── Calls FROM NightFUEL (the Call App workflow node) ─────────────────────
+// ── Calls FROM Nightfuel (the Call App workflow node) ─────────────────────
 //
 // The platform signs every call with the App's NF_APP_CALL_SECRET:
 //   X-NF-App-Call: <base64url(claims)>.<base64url(HMAC-SHA256(secret, claims))>
@@ -278,7 +278,7 @@ function headerValue(headers, name) {
 }
 
 /**
- * Verifies a call made by NightFUEL to this App. `rawBody` is the JSON body
+ * Verifies a call made by Nightfuel to this App. `rawBody` is the JSON body
  * (or the multipart `payload` field) exactly as received. Returns the claims.
  */
 function verifyNightfuelCall({ headers, method, path, rawBody, secret, appId, now = Date.now() } = {}) {

package/package.json

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

package/stream.js

@@ -115,7 +115,7 @@ function responseError(createError, response, payload, afterSeq, reconnects) {
   const auth = status === 401 || status === 403;
   const error = makeError(
     createError,
-    payload?.error || `NightFUEL event stream request failed (${status || 'unknown status'})`,
+    payload?.error || `Nightfuel event stream request failed (${status || 'unknown status'})`,
     {
       status,
       code: payload?.code || (auth ? 'NIGHTFUEL_STREAM_AUTH_FAILED' : 'NIGHTFUEL_STREAM_FAILED'),
@@ -268,7 +268,7 @@ async function* recoverableSseStream(options = {}) {
       idleTimeoutMs,
       onIdle: () => {
         const idle = recoverableError(createError, 'NIGHTFUEL_STREAM_IDLE_TIMEOUT',
-          `NightFUEL event stream was idle for ${idleTimeoutMs}ms`, confirmedSeq, reconnects);
+          `Nightfuel event stream was idle for ${idleTimeoutMs}ms`, confirmedSeq, reconnects);
         attempt.controller.abort(idle);
         return idle;
       },
@@ -314,7 +314,7 @@ async function* recoverableSseStream(options = {}) {
             throw recoverableError(
               createError,
               'NIGHTFUEL_STREAM_TRUNCATED',
-              'NightFUEL event stream ended in the middle of an SSE frame',
+              'Nightfuel event stream ended in the middle of an SSE frame',
               confirmedSeq,
               reconnects
             );
@@ -322,7 +322,7 @@ async function* recoverableSseStream(options = {}) {
           throw recoverableError(
             createError,
             'NIGHTFUEL_STREAM_DROPPED',
-            'NightFUEL event stream closed before a terminal run event',
+            'Nightfuel event stream closed before a terminal run event',
             confirmedSeq,
             reconnects
           );
@@ -337,7 +337,7 @@ async function* recoverableSseStream(options = {}) {
           const rawFrame = buffer.slice(0, boundary.index);
           buffer = buffer.slice(boundary.index + boundary[0].length);
           if (Buffer.byteLength(rawFrame, 'utf8') > MAX_FRAME_BYTES) {
-            throw protocolError(createError, 'NightFUEL stream frame exceeds 8 MiB', confirmedSeq, reconnects);
+            throw protocolError(createError, 'Nightfuel stream frame exceeds 8 MiB', confirmedSeq, reconnects);
           }
           if (!rawFrame || rawFrame.split(/\r?\n/).every((line) => !line || line.startsWith(':'))) continue;
           const frame = parseSseFrame(rawFrame);
@@ -346,7 +346,7 @@ async function* recoverableSseStream(options = {}) {
             const error = recoverableError(
               createError,
               frame.data?.code || 'NIGHTFUEL_STREAM_SERVER_ERROR',
-              frame.data?.error || 'NightFUEL event stream failed after opening',
+              frame.data?.error || 'Nightfuel event stream failed after opening',
               confirmedSeq,
               reconnects,
               null,
@@ -360,7 +360,7 @@ async function* recoverableSseStream(options = {}) {
             throw recoverableError(
               createError,
               'NIGHTFUEL_STREAM_DROPPED',
-              'NightFUEL dropped a slow event subscriber; resuming from the confirmed cursor',
+              'Nightfuel dropped a slow event subscriber; resuming from the confirmed cursor',
               confirmedSeq,
               reconnects,
               null,
@@ -378,7 +378,7 @@ async function* recoverableSseStream(options = {}) {
             throw recoverableError(
               createError,
               'NIGHTFUEL_STREAM_GAP',
-              `NightFUEL event stream expected seq ${confirmedSeq + 1} but received ${seq}`,
+              `Nightfuel event stream expected seq ${confirmedSeq + 1} but received ${seq}`,
               confirmedSeq,
               reconnects,
               null,
@@ -395,7 +395,7 @@ async function* recoverableSseStream(options = {}) {
           if (terminal) return;
         }
         if (Buffer.byteLength(buffer, 'utf8') > MAX_FRAME_BYTES) {
-          throw protocolError(createError, 'NightFUEL stream frame exceeds 8 MiB', confirmedSeq, reconnects);
+          throw protocolError(createError, 'Nightfuel stream frame exceeds 8 MiB', confirmedSeq, reconnects);
         }
       }
     } catch (error) {
@@ -406,7 +406,7 @@ async function* recoverableSseStream(options = {}) {
         ? recoverableError(
             createError,
             'NIGHTFUEL_STREAM_DROPPED',
-            'NightFUEL event stream transport disconnected',
+            'Nightfuel event stream transport disconnected',
             confirmedSeq,
             reconnects,
             error