@nightfuel-ai/app-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @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
+App gateway. It has no browser build and must never be placed in client code.
+
+```bash
+npm install @nightfuel-ai/app-sdk
+```
+
+Node 18 or newer. The package has no dependencies.
+
+```js
+const { createNightfuelAppSdk } = require('@nightfuel-ai/app-sdk');
+
+const nightfuel = createNightfuelAppSdk();
+
+const inventory = await nightfuel.data.query({
+  bindingId: 'inventory',
+  operation: 'query',
+  collection: 'items',
+  filter: { active: true },
+  limit: 50,
+});
+
+await nightfuel.data.mutate({
+  bindingId: 'inventory',
+  operation: 'update',
+  collection: 'items',
+  filter: { sku: 'CAF-001' },
+  update: { available: 12 },
+}, { idempotencyKey: requestId });
+
+const run = await nightfuel.workflows.run('notify-low-stock', {
+  sku: 'CAF-001',
+}, { idempotencyKey: requestId });
+
+const { terminalRunStatus } = require('@nightfuel-ai/app-sdk');
+for await (const event of nightfuel.workflows.stream('notify-low-stock', run.runId, {
+  maxReconnects: 4,
+  reconnectBaseDelayMs: 250,
+  idleTimeoutMs: 90_000,
+})) {
+  if (event.event === 'agent-run:event') {
+    console.log(event.data.seq, event.data.type, event.data.payload);
+  }
+  const terminal = terminalRunStatus(event);
+  if (terminal) console.log(`run ${terminal}`);
+}
+```
+
+## Runtime environment
+
+A Cloud App receives these variables from the platform; the SDK reads them
+unless you pass the matching option:
+
+| Variable | Option | Meaning |
+| --- | --- | --- |
+| `NF_APP_ID` | `appId` | The App's id. |
+| `NF_APP_RUNTIME_AUTH_MODE` | `authMode` | Must be `workload_identity_v1`. |
+| `NF_APP_RUNTIME_API_URL` | `apiUrl` | The private App gateway. |
+| `NF_APP_RUNTIME_AUDIENCE` | `audience` | The identity token audience. |
+| `NF_APP_CALL_SECRET` | `secret` (in `verifyNightfuelCall`) | Verifies calls the platform makes into the App. |
+
+## Streams
+
+The SSE envelope is the same as the persisted run timeline: the outer event is
+`agent-run:event`, while lifecycle and delta names such as `run.completed` and
+`assistant.delta` are in `event.data.type`. The iterator stops after yielding
+`run.completed`, `run.failed`, or `run.cancelled`.
+
+A dropped stream reconnects only the bound stream **GET**, using `afterSeq`
+from the last event acknowledged by the iterator consumer. It never submits
+`workflows.run` again. Retries are bounded and abortable; 401/403/404 responses
+fail immediately, an idle connection uses its own deadline, and explicit slow
+consumer drops resume from the confirmed cursor. An exhausted error includes
+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
+
+The Apphook workflow node signs each request it sends to the App in the
+`X-NF-App-Call` header. `verifyNightfuelCall` checks the signature, expiry,
+App, method, path and body hash, and returns the claims. It makes no network
+call, so a unit test can prove the App rejects a forged request.
+
+```js
+const { verifyNightfuelCall } = require('@nightfuel-ai/app-sdk');
+
+app.post('/webhooks/nightfuel', express.raw({ type: '*/*' }), (req, res) => {
+  try {
+    const claims = verifyNightfuelCall({
+      headers: req.headers, method: 'POST', path: req.originalUrl, rawBody: req.body,
+    });
+    res.json({ ok: true, runId: claims.runId });
+  } catch (error) {
+    res.status(error.status || 401).json({ error: error.message });
+  }
+});
+```
+
+## Bindings
+
+The App reaches only what its bindings allow. A database binding is created in
+Cloud → Apps and is either `read` or explicitly permissioned `read_write`.
+`read_write` is limited to bounded `insert`, filtered `update`, and filtered
+`delete` of records on that exact bound database. It never enables raw
+SQL/Mongo commands, schema changes, index changes, or database credentials.
+A workflow binding pins one workflow version under an App-local name; agents
+create it with the `hosting` tools (`hosting_app_workflow_list_bindable`,
+then `hosting_app_workflow_bindings_update`). `bindingId` is the only
+identifier an App runtime may use; it can never select an arbitrary database,
+workflow, workflow version, or user identity.
+
+The managed Sandbox starter is a Vite frontend, not a production backend: it
+uses the platform's same-origin preview proxies and does not receive this SDK
+in browser source.

package/index.d.ts

@@ -0,0 +1,220 @@
+export interface NightfuelAppSdkErrorOptions {
+  status?: number;
+  code?: string;
+  payload?: unknown;
+}
+
+export class NightfuelAppSdkError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly payload: unknown;
+  readonly afterSeq?: number;
+  readonly reconnects?: number;
+  readonly cause?: unknown;
+  constructor(message: string, options?: NightfuelAppSdkErrorOptions);
+}
+
+export interface NightfuelAppSdkOptions {
+  appId?: string;
+  authMode?: 'workload_identity_v1';
+  apiUrl?: string;
+  audience?: string;
+  metadataUrl?: string;
+  env?: Record<string, string | undefined>;
+  fetch?: typeof fetch;
+}
+
+export interface WorkflowRunAccepted {
+  runId: string;
+  status: string;
+  replay?: boolean;
+  workflowId?: string;
+  workflowVersionId?: string;
+  workflowVersion?: number;
+  streamUrl?: string;
+}
+
+export type NightfuelRunLifecycleType =
+  | 'run.started'
+  | 'run.resumed'
+  | 'run.paused'
+  | 'run.completed'
+  | 'run.failed'
+  | 'run.cancelled';
+export type NightfuelRunDeltaType = 'assistant.delta' | 'assistant.thinking' | 'message.delta' | 'message.token';
+
+export interface NightfuelWorkflowEventData<TType extends string = string, TPayload = Record<string, unknown>> {
+  run_id: string;
+  seq: number;
+  type: TType;
+  timestamp: string;
+  payload: TPayload;
+  turn_id?: string;
+  action_id?: string;
+  [key: string]: unknown;
+}
+
+export interface NightfuelWorkflowLifecyclePayload extends Record<string, unknown> {
+  status?: string;
+  text?: string;
+  error?: string | Record<string, unknown> | null;
+  errorCode?: string | null;
+  resultSummary?: unknown;
+}
+
+export interface NightfuelWorkflowDeltaPayload extends Record<string, unknown> {
+  text?: string;
+  target?: string;
+  format?: string;
+}
+
+export type NightfuelKnownWorkflowEventData =
+  | NightfuelWorkflowEventData<NightfuelRunLifecycleType, NightfuelWorkflowLifecyclePayload>
+  | NightfuelWorkflowEventData<NightfuelRunDeltaType, NightfuelWorkflowDeltaPayload>
+  | NightfuelWorkflowEventData<'tool.started' | 'tool.output' | 'tool.output.available', Record<string, unknown>>
+  | NightfuelWorkflowEventData<
+      | 'workflow.node.started'
+      | 'workflow.node.retry'
+      | 'workflow.node.skipped'
+      | 'workflow.node.cancelled'
+      | 'workflow.node.completed',
+      Record<string, unknown>
+    >;
+
+export interface NightfuelWorkflowDataEvent<T = NightfuelKnownWorkflowEventData | NightfuelWorkflowEventData> {
+  id: string;
+  event: 'agent-run:event';
+  data: T;
+}
+
+export interface NightfuelWorkflowReadyEvent {
+  id: string;
+  event: 'agent-run:ready';
+  data: { runId: string; afterSeq: number };
+}
+
+export interface NightfuelWorkflowHeartbeatEvent {
+  id: string;
+  event: 'agent-run:heartbeat';
+  data: {
+    runId: string;
+    lastSeq: number;
+    paused: boolean;
+    queueDepth: number;
+    eventsDropped: number;
+    [key: string]: unknown;
+  };
+}
+
+export interface NightfuelWorkflowDroppedEvent {
+  id: string;
+  event: 'agent-run:dropped';
+  data: {
+    runId: string;
+    reason: 'subscriber_queue_overflow' | string;
+    eventsDropped: number;
+    queueHighWater: number;
+    [key: string]: unknown;
+  };
+}
+
+export type NightfuelWorkflowEvent<T = NightfuelKnownWorkflowEventData | NightfuelWorkflowEventData> =
+  | NightfuelWorkflowDataEvent<T>
+  | NightfuelWorkflowReadyEvent
+  | NightfuelWorkflowHeartbeatEvent
+  | NightfuelWorkflowDroppedEvent;
+
+export function terminalRunStatus(
+  event: NightfuelWorkflowEvent
+): 'completed' | 'failed' | 'cancelled' | null;
+
+export interface NightfuelWorkflowStreamOptions {
+  /** Starts after a cursor already committed by the App. */
+  afterSeq?: number | string;
+  /** Reconnects allowed without another acknowledged durable event. Default 4. */
+  maxReconnects?: number;
+  /** Initial exponential reconnect delay. Default 250ms, capped at 30000ms. */
+  reconnectBaseDelayMs?: number;
+  /** Reconnect when no stream bytes arrive by this deadline. Default 90000ms. */
+  idleTimeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface NightfuelDataClient {
+  query<T = unknown>(input?: Record<string, unknown>): Promise<T>;
+  semantic<T = unknown>(input?: Record<string, unknown>): Promise<T>;
+  mutate<T = unknown>(
+    input: NightfuelDatabaseMutationInput,
+    options: { idempotencyKey: string }
+  ): Promise<T>;
+}
+
+export type NightfuelDatabaseMutationOperation = 'insert' | 'update' | 'delete';
+
+export interface NightfuelDatabaseMutationInput {
+  bindingId: string;
+  operation: NightfuelDatabaseMutationOperation;
+  collection: string;
+  documents?: Array<Record<string, unknown>>;
+  filter?: Record<string, unknown>;
+  update?: Record<string, unknown>;
+}
+
+export interface NightfuelWorkflowClient {
+  run(
+    bindingId: string,
+    input: Record<string, unknown>,
+    options: { idempotencyKey: string }
+  ): Promise<WorkflowRunAccepted>;
+  stream<T = NightfuelKnownWorkflowEventData | NightfuelWorkflowEventData>(
+    bindingId: string,
+    runId: string,
+    options?: NightfuelWorkflowStreamOptions
+  ): AsyncGenerator<NightfuelWorkflowEvent<T>, void, undefined>;
+}
+
+export interface NightfuelAppSdk {
+  readonly appId: string;
+  readonly data: NightfuelDataClient;
+  readonly workflows: NightfuelWorkflowClient;
+  createIdempotencyKey(): string;
+}
+
+export function createNightfuelAppSdk(options?: NightfuelAppSdkOptions): NightfuelAppSdk;
+
+/** The claims NightFUEL signs into an Apphook request. */
+export interface NightfuelCallClaims {
+  v: 1;
+  appId: string;
+  projectId: string;
+  method: string;
+  path: string;
+  /** SHA-256 (hex) of the JSON body, or of the multipart `payload` field. */
+  bodySha256: string;
+  runId: string;
+  nodeId: string;
+  iat: number;
+  exp: number;
+  nonce: string;
+}
+
+/**
+ * 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.
+ */
+export function verifyNightfuelCall(input: {
+  headers: Headers | Record<string, string | string[] | undefined>;
+  /** Pin the method the token was issued for. Omit to skip the check. */
+  method?: string;
+  /** Pin the path the token was issued for. Omit to skip the check. */
+  path?: string;
+  /** Omit to skip the body check; pass the raw bytes to enforce it. */
+  rawBody?: string | Buffer;
+  /** Defaults to process.env.NF_APP_CALL_SECRET. */
+  secret?: string;
+  /** Defaults to process.env.NF_APP_ID. */
+  appId?: string;
+  now?: number;
+}): NightfuelCallClaims;

package/index.js

@@ -0,0 +1,339 @@
+'use strict';
+
+// @nightfuel-ai/app-sdk
+//
+// 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.
+
+const crypto = require('crypto');
+const { parseSseFrame, recoverableSseStream, terminalRunStatus } = require('./stream');
+
+const METADATA_IDENTITY_URL =
+  'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity';
+const APP_ID_RE = /^[a-f\d]{24}$/i;
+const BINDING_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,255}$/;
+const MUTATION_IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/;
+
+class NightfuelAppSdkError extends Error {
+  constructor(message, { status = 0, code = '', payload = null } = {}) {
+    super(message);
+    this.name = 'NightfuelAppSdkError';
+    this.status = status;
+    this.code = code;
+    this.payload = payload;
+  }
+}
+
+function requiredServerRuntime() {
+  if (typeof window !== 'undefined' || typeof document !== 'undefined') {
+    throw new NightfuelAppSdkError(
+      '@nightfuel-ai/app-sdk is server-only. Browser code must call its own App backend.',
+      { code: 'NIGHTFUEL_APP_SDK_BROWSER_FORBIDDEN' }
+    );
+  }
+}
+
+function httpsOrigin(value, name) {
+  const raw = String(value || '').trim();
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new NightfuelAppSdkError(`${name} must be an HTTPS origin`, { code: 'NIGHTFUEL_APP_SDK_CONFIG_INVALID' });
+  }
+  if (url.protocol !== 'https:' || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new NightfuelAppSdkError(`${name} must be an HTTPS origin`, { code: 'NIGHTFUEL_APP_SDK_CONFIG_INVALID' });
+  }
+  return url.origin;
+}
+
+function requiredAppId(value) {
+  const appId = String(value || '').trim().toLowerCase();
+  if (!APP_ID_RE.test(appId)) {
+    throw new NightfuelAppSdkError('NF_APP_ID must be a Hosted App ObjectId', { code: 'NIGHTFUEL_APP_SDK_CONFIG_INVALID' });
+  }
+  return appId;
+}
+
+function bindingId(value) {
+  const normalized = String(value || '').trim();
+  if (!BINDING_ID_RE.test(normalized)) {
+    throw new NightfuelAppSdkError('workflow bindingId is invalid', { code: 'NIGHTFUEL_APP_SDK_BINDING_INVALID' });
+  }
+  return normalized;
+}
+
+function idempotencyKey(value) {
+  const normalized = String(value || '').trim();
+  if (!IDEMPOTENCY_KEY_RE.test(normalized)) {
+    throw new NightfuelAppSdkError(
+      'workflows.run requires a stable 8-256 character idempotencyKey; reuse it for transport retries.',
+      { code: 'NIGHTFUEL_APP_SDK_IDEMPOTENCY_KEY_INVALID' }
+    );
+  }
+  return normalized;
+}
+
+function mutationIdempotencyKey(value) {
+  const normalized = String(value || '').trim();
+  if (!MUTATION_IDEMPOTENCY_KEY_RE.test(normalized)) {
+    throw new NightfuelAppSdkError(
+      'data.mutate requires a stable 8-128 character idempotencyKey; reuse it for transport retries.',
+      { code: 'NIGHTFUEL_APP_SDK_MUTATION_IDEMPOTENCY_KEY_INVALID' }
+    );
+  }
+  return normalized;
+}
+
+function parseJwtExpiry(token) {
+  const part = String(token || '').split('.')[1];
+  if (!part) return 0;
+  try {
+    const payload = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+    return Number(payload?.exp || 0) * 1000;
+  } catch {
+    return 0;
+  }
+}
+
+async function responsePayload(response) {
+  const contentType = String(response.headers?.get?.('content-type') || '').toLowerCase();
+  const text = await response.text();
+  if (!text) return null;
+  if (contentType.includes('application/json')) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { raw: text };
+    }
+  }
+  return { raw: text };
+}
+
+function createNightfuelAppSdk(options = {}) {
+  requiredServerRuntime();
+  const env = options.env || process.env;
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new NightfuelAppSdkError('A fetch implementation is required', { code: 'NIGHTFUEL_APP_SDK_FETCH_REQUIRED' });
+  }
+  const appId = requiredAppId(options.appId || env.NF_APP_ID);
+  const authMode = String(options.authMode || env.NF_APP_RUNTIME_AUTH_MODE || '').trim();
+  if (authMode !== 'workload_identity_v1') {
+    throw new NightfuelAppSdkError(
+      '@nightfuel-ai/app-sdk requires NF_APP_RUNTIME_AUTH_MODE=workload_identity_v1',
+      { code: 'NIGHTFUEL_APP_SDK_AUTH_MODE_INVALID' }
+    );
+  }
+  const apiUrl = httpsOrigin(options.apiUrl || env.NF_APP_RUNTIME_API_URL, 'NF_APP_RUNTIME_API_URL');
+  const audience = httpsOrigin(options.audience || env.NF_APP_RUNTIME_AUDIENCE, 'NF_APP_RUNTIME_AUDIENCE');
+  const metadataUrl = String(options.metadataUrl || METADATA_IDENTITY_URL).trim();
+  let cachedToken = null;
+
+  async function workloadIdentityToken(signal) {
+    signal?.throwIfAborted();
+    if (cachedToken?.expiresAt > Date.now() + 300_000) return cachedToken.token;
+    const response = await fetchImpl(
+      `${metadataUrl}?audience=${encodeURIComponent(audience)}&format=full`,
+      { headers: { 'Metadata-Flavor': 'Google' }, signal }
+    );
+    signal?.throwIfAborted();
+    if (!response.ok) {
+      throw new NightfuelAppSdkError(`Cloud Run workload identity request failed (${response.status})`, {
+        status: response.status,
+        code: 'NIGHTFUEL_APP_SDK_IDENTITY_UNAVAILABLE',
+      });
+    }
+    const token = String(await response.text()).trim();
+    const expiresAt = parseJwtExpiry(token);
+    if (!token || !expiresAt || expiresAt <= Date.now()) {
+      throw new NightfuelAppSdkError('Cloud Run workload identity token is malformed or expired', {
+        code: 'NIGHTFUEL_APP_SDK_IDENTITY_INVALID',
+      });
+    }
+    cachedToken = { token, expiresAt };
+    return token;
+  }
+
+  async function request(path, init = {}, { allowErrorResponse = false } = {}) {
+    init.signal?.throwIfAborted();
+    const headers = new Headers(init.headers || {});
+    headers.set('Authorization', `Bearer ${await workloadIdentityToken(init.signal)}`);
+    init.signal?.throwIfAborted();
+    headers.set('Accept', headers.get('Accept') || 'application/json');
+    const response = await fetchImpl(`${apiUrl}${path}`, { ...init, headers });
+    init.signal?.throwIfAborted();
+    if (!response.ok && !allowErrorResponse) {
+      const payload = await responsePayload(response);
+      throw new NightfuelAppSdkError(
+        payload?.error || `NightFUEL App gateway request failed (${response.status})`,
+        { status: response.status, code: payload?.code || 'NIGHTFUEL_APP_SDK_GATEWAY_ERROR', payload }
+      );
+    }
+    return response;
+  }
+
+  async function postJson(path, body, headers = {}) {
+    const response = await request(path, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify(body),
+    });
+    return responsePayload(response);
+  }
+
+  return Object.freeze({
+    appId,
+    data: Object.freeze({
+      query: (input) => postJson(`/internal/hosting/apps/${appId}/data/query`, input || {}),
+      semantic: (input) => postJson(`/internal/hosting/apps/${appId}/data/semantic`, input || {}),
+      // Keep the public async contract consistent with the other gateway
+      // methods: invalid keys are a rejected Promise instead of a synchronous
+      // throw while evaluating an argument to postJson.
+      async mutate(input, options = {}) {
+        const key = mutationIdempotencyKey(options.idempotencyKey);
+        return postJson(
+          `/internal/hosting/apps/${appId}/data/mutate`,
+          input || {},
+          { 'Idempotency-Key': key }
+        );
+      },
+    }),
+    workflows: Object.freeze({
+      async run(rawBindingId, input = {}, options = {}) {
+        const resolvedBindingId = bindingId(rawBindingId);
+        const key = idempotencyKey(options.idempotencyKey);
+        return postJson(
+          `/internal/hosting/apps/${appId}/workflows/${encodeURIComponent(resolvedBindingId)}/runs`,
+          { input },
+          { 'Idempotency-Key': key }
+        );
+      },
+      async *stream(rawBindingId, runId, options = {}) {
+        const resolvedBindingId = bindingId(rawBindingId);
+        const normalizedRunId = String(runId || '').trim();
+        if (!normalizedRunId) {
+          throw new NightfuelAppSdkError('workflow runId is required', { code: 'NIGHTFUEL_APP_SDK_RUN_ID_REQUIRED' });
+        }
+        const hadExplicitCursor = options.afterSeq !== undefined && options.afterSeq !== null;
+        yield* recoverableSseStream({
+          runId: normalizedRunId,
+          afterSeq: options.afterSeq,
+          signal: options.signal,
+          maxReconnects: options.maxReconnects,
+          reconnectBaseDelayMs: options.reconnectBaseDelayMs,
+          idleTimeoutMs: options.idleTimeoutMs,
+          createError(message, details) {
+            return new NightfuelAppSdkError(message, {
+              status: details.status,
+              code: details.code,
+              payload: details.payload,
+            });
+          },
+          open: ({ afterSeq, initial, signal }) => {
+            const query = !initial || hadExplicitCursor
+              ? `?afterSeq=${encodeURIComponent(String(afterSeq))}`
+              : '';
+            return request(
+              `/internal/hosting/apps/${appId}/workflows/${encodeURIComponent(resolvedBindingId)}/runs/${encodeURIComponent(normalizedRunId)}/events/stream${query}`,
+              { method: 'GET', headers: { Accept: 'text/event-stream' }, signal },
+              { allowErrorResponse: true }
+            );
+          },
+        });
+      },
+    }),
+    createIdempotencyKey: () => crypto.randomUUID(),
+  });
+}
+
+// ── 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))>
+//   claims = { v: 1, appId, projectId, method, path, bodySha256, runId, nodeId, iat, exp, nonce }
+// `bodySha256` is the SHA-256 (hex) of the JSON payload: the raw body for JSON
+// requests, or the `payload` field for multipart requests, whose `files[]`
+// entries carry each attachment's own sha256. Verify before acting.
+const APP_CALL_TOKEN_VERSION = 1;
+const APP_CALL_CLOCK_SKEW_MS = 30_000;
+
+function callVerificationError(message, code) {
+  return new NightfuelAppSdkError(message, { status: 401, code });
+}
+
+function sha256Hex(value) {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value === undefined || value === null ? '' : String(value), 'utf8');
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function headerValue(headers, name) {
+  if (!headers) return '';
+  if (typeof headers.get === 'function') return String(headers.get(name) || '');
+  const key = Object.keys(headers).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+  const value = key ? headers[key] : '';
+  return String(Array.isArray(value) ? value[0] : value || '');
+}
+
+/**
+ * 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() } = {}) {
+  const resolvedSecret = String(secret || process.env.NF_APP_CALL_SECRET || '');
+  if (!resolvedSecret) {
+    throw new NightfuelAppSdkError('NF_APP_CALL_SECRET is not configured for this App', { status: 503, code: 'NIGHTFUEL_APP_CALL_SECRET_MISSING' });
+  }
+  const token = headerValue(headers, 'x-nf-app-call').trim();
+  const [payload, signed, extra] = token.split('.');
+  if (!payload || !signed || extra) throw callVerificationError('Missing or malformed X-NF-App-Call token', 'NIGHTFUEL_APP_CALL_TOKEN_INVALID');
+  const expected = crypto.createHmac('sha256', resolvedSecret).update(payload).digest('base64url');
+  const left = Buffer.from(signed, 'utf8');
+  const right = Buffer.from(expected, 'utf8');
+  if (left.length !== right.length || !crypto.timingSafeEqual(left, right)) {
+    throw callVerificationError('X-NF-App-Call signature is invalid', 'NIGHTFUEL_APP_CALL_TOKEN_INVALID');
+  }
+  let claims;
+  try {
+    claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+  } catch {
+    throw callVerificationError('X-NF-App-Call payload is invalid', 'NIGHTFUEL_APP_CALL_TOKEN_INVALID');
+  }
+  if (claims.v !== APP_CALL_TOKEN_VERSION || Number(claims.exp) <= now || Number(claims.iat) > now + APP_CALL_CLOCK_SKEW_MS) {
+    throw callVerificationError('X-NF-App-Call token has expired', 'NIGHTFUEL_APP_CALL_TOKEN_EXPIRED');
+  }
+  const expectedAppId = String(appId || process.env.NF_APP_ID || '').trim().toLowerCase();
+  if (expectedAppId && String(claims.appId || '').toLowerCase() !== expectedAppId) {
+    throw new NightfuelAppSdkError('X-NF-App-Call token belongs to another App', { status: 403, code: 'NIGHTFUEL_APP_CALL_TOKEN_SCOPE_MISMATCH' });
+  }
+  if (method !== undefined && claims.method !== String(method || '').trim().toUpperCase()) {
+    throw new NightfuelAppSdkError('X-NF-App-Call token was issued for another method', { status: 403, code: 'NIGHTFUEL_APP_CALL_TOKEN_SCOPE_MISMATCH' });
+  }
+  if (path !== undefined) {
+    const normalizedPath = String(path || '/').trim();
+    if (claims.path !== (normalizedPath.startsWith('/') ? normalizedPath : `/${normalizedPath}`)) {
+      throw new NightfuelAppSdkError('X-NF-App-Call token was issued for another path', { status: 403, code: 'NIGHTFUEL_APP_CALL_TOKEN_SCOPE_MISMATCH' });
+    }
+  }
+  if (rawBody !== undefined && String(claims.bodySha256) !== sha256Hex(rawBody)) {
+    throw new NightfuelAppSdkError('X-NF-App-Call token does not match the request body', { status: 403, code: 'NIGHTFUEL_APP_CALL_TOKEN_SCOPE_MISMATCH' });
+  }
+  return claims;
+}
+
+module.exports = {
+  NightfuelAppSdkError,
+  createNightfuelAppSdk,
+  terminalRunStatus,
+  verifyNightfuelCall,
+  _test: {
+    bindingId,
+    httpsOrigin,
+    idempotencyKey,
+    mutationIdempotencyKey,
+    parseJwtExpiry,
+    parseSseFrame,
+  },
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@nightfuel-ai/app-sdk",
+  "version": "0.1.0",
+  "description": "Server-only NightFUEL SDK for a hosted App workload identity.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "stream.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KrozraM/NightFUEL.git",
+    "directory": "Backend/nightfuel_api/hosting/app-sdk"
+  },
+  "keywords": [
+    "nightfuel",
+    "apps",
+    "workload-identity",
+    "workflows",
+    "sdk"
+  ]
+}

package/stream.js

@@ -0,0 +1,437 @@
+'use strict';
+
+// This file is also vendored byte-for-byte into hosting/app-sdk/stream.js.
+// The two packages are published independently, so a runtime relative import
+// would break one of the standalone artifacts. tests/sdk_stream_recovery.test
+// enforces parity between the two copies.
+
+const DEFAULT_MAX_RECONNECTS = 4;
+const DEFAULT_RECONNECT_BASE_DELAY_MS = 250;
+const DEFAULT_IDLE_TIMEOUT_MS = 90_000;
+const MAX_RECONNECT_DELAY_MS = 30_000;
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const RETRYABLE_HTTP_STATUSES = new Set([429, 502, 503, 504]);
+const TERMINAL_RUN_EVENT_TYPES = new Set(['run.completed', 'run.failed', 'run.cancelled']);
+
+function parseSseFrame(frame) {
+  const lines = String(frame || '').replace(/\r/g, '').split('\n');
+  let event = 'message';
+  let id = '';
+  const dataLines = [];
+  for (const line of lines) {
+    if (!line || line.startsWith(':')) continue;
+    const separator = line.indexOf(':');
+    const field = separator < 0 ? line : line.slice(0, separator);
+    const value = (separator < 0 ? '' : line.slice(separator + 1)).replace(/^ /, '');
+    if (field === 'event') event = value || event;
+    else if (field === 'id') id = value;
+    else if (field === 'data') dataLines.push(value);
+  }
+  const rawData = dataLines.join('\n');
+  let data = rawData;
+  if (rawData) {
+    try { data = JSON.parse(rawData); } catch { /* preserve non-JSON control events */ }
+  }
+  return { event, id, data };
+}
+
+function integerOption(value, fallback, name, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (value === undefined || value === null) return fallback;
+  const number = typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : value;
+  if (!Number.isSafeInteger(number) || number < min || number > max) {
+    const error = new TypeError(`${name} must be an integer from ${min} to ${max}`);
+    error.code = 'NIGHTFUEL_STREAM_OPTIONS_INVALID';
+    throw error;
+  }
+  return number;
+}
+
+function withDetails(error, details = {}) {
+  if (!error || typeof error !== 'object') return error;
+  if (details.cause !== undefined && error.cause === undefined) error.cause = details.cause;
+  if (details.afterSeq !== undefined) error.afterSeq = details.afterSeq;
+  if (details.reconnects !== undefined) error.reconnects = details.reconnects;
+  if (details.payload !== undefined && error.payload === undefined) error.payload = details.payload;
+  return error;
+}
+
+function defaultError(message, details = {}) {
+  const error = new Error(message);
+  error.name = 'NightfuelStreamError';
+  error.status = Number(details.status || 0);
+  error.code = String(details.code || 'NIGHTFUEL_STREAM_FAILED');
+  return withDetails(error, details);
+}
+
+function makeError(createError, message, details = {}) {
+  return withDetails((createError || defaultError)(message, details), details);
+}
+
+function abortableSleep(ms, signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', onAbort);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    timer.unref?.();
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function reconnectDelay(error, reconnects, baseDelayMs) {
+  if (Number.isFinite(error?.retryAfterMs) && error.retryAfterMs >= 0) {
+    return Math.min(error.retryAfterMs, MAX_RECONNECT_DELAY_MS);
+  }
+  const exponential = Math.min(baseDelayMs * (2 ** Math.max(0, reconnects - 1)), MAX_RECONNECT_DELAY_MS);
+  const jitter = baseDelayMs > 0 ? Math.floor(Math.random() * baseDelayMs) : 0;
+  return Math.min(exponential + jitter, MAX_RECONNECT_DELAY_MS);
+}
+
+function retryAfterMs(response) {
+  const raw = response?.headers?.get?.('retry-after');
+  if (raw == null || raw.trim() === '') return null;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
+}
+
+async function errorPayload(response) {
+  try {
+    const text = await response.text();
+    if (!text) return null;
+    try { return JSON.parse(text); } catch { return { raw: text }; }
+  } catch {
+    return null;
+  }
+}
+
+function responseError(createError, response, payload, afterSeq, reconnects) {
+  const status = Number(response?.status || 0);
+  const auth = status === 401 || status === 403;
+  const error = makeError(
+    createError,
+    payload?.error || `NightFUEL event stream request failed (${status || 'unknown status'})`,
+    {
+      status,
+      code: payload?.code || (auth ? 'NIGHTFUEL_STREAM_AUTH_FAILED' : 'NIGHTFUEL_STREAM_FAILED'),
+      payload,
+      afterSeq,
+      reconnects,
+    }
+  );
+  error.retryable = RETRYABLE_HTTP_STATUSES.has(status);
+  error.retryAfterMs = retryAfterMs(response);
+  return error;
+}
+
+function protocolError(createError, message, afterSeq, reconnects, payload = null) {
+  const error = makeError(createError, message, {
+    code: 'NIGHTFUEL_STREAM_PROTOCOL_ERROR', payload, afterSeq, reconnects,
+  });
+  error.retryable = false;
+  return error;
+}
+
+function recoverableError(createError, code, message, afterSeq, reconnects, cause = null, payload = null) {
+  const error = makeError(createError, message, {
+    code, cause, payload, afterSeq, reconnects,
+  });
+  error.retryable = true;
+  return error;
+}
+
+function eventSequence(frame, { runId, afterSeq, reconnects, createError }) {
+  const data = frame?.data;
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw protocolError(createError, 'agent-run:event data must be a JSON object', afterSeq, reconnects, data);
+  }
+  const seq = data.seq;
+  if (!Number.isSafeInteger(seq) || seq <= 0 || frame.id !== String(seq)) {
+    throw protocolError(
+      createError,
+      'agent-run:event must carry the same positive integer in SSE id and data.seq',
+      afterSeq,
+      reconnects,
+      data
+    );
+  }
+  if (typeof data.type !== 'string' || !data.type.trim()) {
+    throw protocolError(createError, 'agent-run:event data.type is required', afterSeq, reconnects, data);
+  }
+  const eventRunId = String(data.run_id || '').trim();
+  if (eventRunId !== runId) {
+    throw protocolError(createError, 'agent-run:event belongs to another run', afterSeq, reconnects, data);
+  }
+  return seq;
+}
+
+function attemptController(parentSignal) {
+  parentSignal?.throwIfAborted();
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(parentSignal.reason);
+  parentSignal?.addEventListener('abort', onAbort, { once: true });
+  return {
+    controller,
+    cleanup() { parentSignal?.removeEventListener('abort', onAbort); },
+  };
+}
+
+function boundedStep(operation, { signal, idleTimeoutMs, onIdle }) {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener('abort', onAbort);
+      fn(value);
+    };
+    const onAbort = () => finish(reject, signal.reason);
+    const timer = setTimeout(() => finish(reject, onIdle()), idleTimeoutMs);
+    timer.unref?.();
+    signal.addEventListener('abort', onAbort, { once: true });
+    Promise.resolve().then(operation).then(
+      (value) => finish(resolve, value),
+      (error) => finish(reject, error)
+    );
+  });
+}
+
+function discardTransport(opened, iterator) {
+  // An async generator may be stuck in next(), in which case return() also
+  // waits forever. Abort the transport separately and never await its teardown.
+  try { Promise.resolve(iterator?.return?.()).catch(() => {}); } catch { /* closed */ }
+  try { opened?.cleanup?.(); } catch { /* already discarded */ }
+}
+
+function shouldRetry(error) {
+  if (!error || typeof error !== 'object') return true;
+  if (error.retryable === false) return false;
+  if ([401, 403, 404].includes(Number(error.status || 0))) return false;
+  if (error.code === 'NIGHTFUEL_STREAM_PROTOCOL_ERROR') return false;
+  return true;
+}
+
+function terminalRunStatus(frame) {
+  if (frame?.event !== 'agent-run:event') return null;
+  const type = frame?.data?.type;
+  if (type === 'run.completed') return 'completed';
+  if (type === 'run.failed') return 'failed';
+  if (type === 'run.cancelled') return 'cancelled';
+  return null;
+}
+
+/**
+ * Reconnects an SSE GET from the last event the consumer confirmed.
+ *
+ * Confirmation happens after `yield`: the cursor advances only when the
+ * consumer asks this generator for its next value. If consumer code throws or
+ * returns while handling an event, that event remains unconfirmed and is safe
+ * to replay from the caller's persisted cursor.
+ */
+async function* recoverableSseStream(options = {}) {
+  if (typeof options.open !== 'function') throw new TypeError('open must be a function');
+  const runId = String(options.runId || '').trim();
+  if (!runId) throw new TypeError('runId is required');
+  const createError = options.createError || defaultError;
+  let confirmedSeq = integerOption(options.afterSeq, 0, 'afterSeq');
+  const maxReconnects = integerOption(options.maxReconnects, DEFAULT_MAX_RECONNECTS, 'maxReconnects', { max: 100 });
+  const reconnectBaseDelayMs = integerOption(
+    options.reconnectBaseDelayMs,
+    DEFAULT_RECONNECT_BASE_DELAY_MS,
+    'reconnectBaseDelayMs',
+    { max: MAX_RECONNECT_DELAY_MS }
+  );
+  const idleTimeoutMs = integerOption(
+    options.idleTimeoutMs,
+    DEFAULT_IDLE_TIMEOUT_MS,
+    'idleTimeoutMs',
+    { min: 1, max: 86_400_000 }
+  );
+  const callerSignal = options.signal;
+  let reconnects = 0;
+  let lastError = null;
+
+  while (true) {
+    callerSignal?.throwIfAborted();
+    const attempt = attemptController(callerSignal);
+    let opened = null;
+    let iterator = null;
+    const deadline = {
+      signal: attempt.controller.signal,
+      idleTimeoutMs,
+      onIdle: () => {
+        const idle = recoverableError(createError, 'NIGHTFUEL_STREAM_IDLE_TIMEOUT',
+          `NightFUEL event stream was idle for ${idleTimeoutMs}ms`, confirmedSeq, reconnects);
+        attempt.controller.abort(idle);
+        return idle;
+      },
+    };
+    try {
+      opened = await boundedStep(async () => {
+        const connection = await options.open({
+          afterSeq: confirmedSeq,
+          initial: reconnects === 0 && confirmedSeq === Number(options.afterSeq || 0),
+          reconnects,
+          signal: attempt.controller.signal,
+        });
+        if (attempt.controller.signal.aborted) {
+          const body = (connection?.response || connection)?.body;
+          discardTransport(connection, body?.[Symbol.asyncIterator]?.());
+          attempt.controller.signal.throwIfAborted();
+        }
+        return connection;
+      }, deadline);
+      attempt.controller.signal.throwIfAborted();
+      const response = opened?.response || opened;
+      if (!response || typeof response.ok !== 'boolean') {
+        throw protocolError(createError, 'The event stream returned no HTTP response', confirmedSeq, reconnects);
+      }
+      if (!response.ok) {
+        // Even a broken error body must retain its HTTP authorization status.
+        let payload = null;
+        try { payload = await boundedStep(() => errorPayload(response), deadline); } catch { /* use HTTP status */ }
+        throw responseError(createError, response, payload, confirmedSeq, reconnects);
+      }
+      if (!response.body || typeof response.body[Symbol.asyncIterator] !== 'function') {
+        throw protocolError(createError, 'The event stream has no async response body', confirmedSeq, reconnects);
+      }
+
+      iterator = response.body[Symbol.asyncIterator]();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      while (true) {
+        const chunk = await boundedStep(() => iterator.next(), deadline);
+        if (chunk.done) {
+          buffer += decoder.decode();
+          if (buffer.trim()) {
+            throw recoverableError(
+              createError,
+              'NIGHTFUEL_STREAM_TRUNCATED',
+              'NightFUEL event stream ended in the middle of an SSE frame',
+              confirmedSeq,
+              reconnects
+            );
+          }
+          throw recoverableError(
+            createError,
+            'NIGHTFUEL_STREAM_DROPPED',
+            'NightFUEL event stream closed before a terminal run event',
+            confirmedSeq,
+            reconnects
+          );
+        }
+
+        buffer += typeof chunk.value === 'string'
+          ? chunk.value
+          : decoder.decode(chunk.value, { stream: true });
+        let boundary;
+        while ((boundary = /\r?\n\r?\n/.exec(buffer))) {
+          attempt.controller.signal.throwIfAborted();
+          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);
+          }
+          if (!rawFrame || rawFrame.split(/\r?\n/).every((line) => !line || line.startsWith(':'))) continue;
+          const frame = parseSseFrame(rawFrame);
+
+          if (frame.event === 'agent-run:error') {
+            const error = recoverableError(
+              createError,
+              frame.data?.code || 'NIGHTFUEL_STREAM_SERVER_ERROR',
+              frame.data?.error || 'NightFUEL event stream failed after opening',
+              confirmedSeq,
+              reconnects,
+              null,
+              frame.data
+            );
+            if (frame.data?.recoverable === false) error.retryable = false;
+            throw error;
+          }
+          if (frame.event === 'agent-run:dropped') {
+            yield frame;
+            throw recoverableError(
+              createError,
+              'NIGHTFUEL_STREAM_DROPPED',
+              'NightFUEL dropped a slow event subscriber; resuming from the confirmed cursor',
+              confirmedSeq,
+              reconnects,
+              null,
+              frame.data
+            );
+          }
+          if (frame.event !== 'agent-run:event') {
+            yield frame;
+            continue;
+          }
+
+          const seq = eventSequence(frame, { runId, afterSeq: confirmedSeq, reconnects, createError });
+          if (seq <= confirmedSeq) continue;
+          if (seq !== confirmedSeq + 1) {
+            throw recoverableError(
+              createError,
+              'NIGHTFUEL_STREAM_GAP',
+              `NightFUEL event stream expected seq ${confirmedSeq + 1} but received ${seq}`,
+              confirmedSeq,
+              reconnects,
+              null,
+              frame.data
+            );
+          }
+
+          const terminal = TERMINAL_RUN_EVENT_TYPES.has(frame.data.type);
+          yield frame;
+          // Reaching this line is the acknowledgement boundary: the consumer
+          // asked for another event after receiving this one.
+          confirmedSeq = seq;
+          reconnects = 0;
+          if (terminal) return;
+        }
+        if (Buffer.byteLength(buffer, 'utf8') > MAX_FRAME_BYTES) {
+          throw protocolError(createError, 'NightFUEL stream frame exceeds 8 MiB', confirmedSeq, reconnects);
+        }
+      }
+    } catch (error) {
+      callerSignal?.throwIfAborted();
+      const classified = shouldRetry(error)
+        && !error?.code
+        && !Number(error?.status || 0)
+        ? recoverableError(
+            createError,
+            'NIGHTFUEL_STREAM_DROPPED',
+            'NightFUEL event stream transport disconnected',
+            confirmedSeq,
+            reconnects,
+            error
+          )
+        : error;
+      lastError = classified;
+      if (!shouldRetry(classified) || reconnects >= maxReconnects) {
+        throw withDetails(classified, { afterSeq: confirmedSeq, reconnects });
+      }
+      reconnects += 1;
+    } finally {
+      if (!attempt.controller.signal.aborted) attempt.controller.abort();
+      discardTransport(opened, iterator);
+      attempt.cleanup();
+    }
+
+    await abortableSleep(reconnectDelay(lastError, reconnects, reconnectBaseDelayMs), callerSignal);
+  }
+}
+
+module.exports = {
+  DEFAULT_IDLE_TIMEOUT_MS,
+  DEFAULT_MAX_RECONNECTS,
+  DEFAULT_RECONNECT_BASE_DELAY_MS,
+  parseSseFrame,
+  recoverableSseStream,
+  terminalRunStatus,
+};