@nightfuel-ai/app-sdk 0.1.1 → 0.3.0

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
@@ -116,3 +133,170 @@ 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.
+# Typed App events (On App)
+
+Declare events in server code with `defineAppEvents` and `eventSchema`. The same
+definition supplies TypeScript payload inference and a bounded JSON Schema
+manifest. It is compatible with CommonJS and native ESM.
+
+```ts
+import { defineAppEvents, eventSchema as s, createNightfuelAppSdk } from '@nightfuel-ai/app-sdk';
+import { writeFileSync } from 'node:fs';
+
+export const events = defineAppEvents({
+  'booking.created': {
+    version: 1,
+    title: 'Booking created',
+    payload: s.object({
+      bookingId: s.string({ minLength: 1 }),
+      propertyId: s.string({ minLength: 1 }),
+      nights: s.integer({ minimum: 1 }),
+      channel: s.enum('site', 'whatsapp'),
+    }),
+  },
+});
+// Run in a build/generation script and commit the generated file.
+writeFileSync('.nightfuel/events.json', JSON.stringify(events.manifest, null, 2) + '\n');
+const nf = createNightfuelAppSdk({ events });
+await nf.events.emit('booking.created', {
+  bookingId: 'b1', propertyId: 'hotel-1', nights: 3, channel: 'site',
+}, {
+  idempotencyKey: 'booking-b1-created-v1',
+  occurredAt: '2026-10-20T10:00:00.000Z',
+});
+```
+
+NightFUEL indexes `.nightfuel/events.json` while ingesting source. It does not
+execute code or request a discovery endpoint on the App. The workflow editor
+and `hosting_app_event_catalog_list` select the exact App/environment, event
+path, immutable version and hash from platform storage. Previously registered
+versions remain available for pinned workflows. Increment `version` whenever
+the payload schema changes; reusing a version with a different schema is rejected.
+
+`events.emit` is server-only and uses the App's workload identity. It validates
+the payload before sending it; the platform validates it again. A `202` receipt
+means durable acceptance, not workflow completion. Keep the same idempotency key,
+occurrence time and payload on retries. Reusing a key for a different event
+returns `409`. Mutating requests are not automatically retried by the SDK.
+
+For business mutations, commit an outbox row in the same database transaction
+as the mutation. A worker sends the persisted event and marks the row delivered
+only after acceptance. The App being off prevents new emissions; it does not
+remove discovery or interrupt delivery of events already accepted by NightFUEL.
+An in-memory queue or fire-and-forget call is not a transactional outbox.
+
+Schemas support closed objects, optional properties, arrays, homogeneous enums,
+strings (including `date`, `date-time`, `uuid`), numbers, integers and booleans,
+with bounded lengths and numeric ranges. Root payloads must be objects.
+Manifests and emission envelopes are limited to 256 KiB; each manifest may
+declare at most 100 event paths. Unsupported JSON Schema features are rejected.
+
+## App credentials, Calendar and durable callbacks
+
+Version `0.3.0` adds App-scoped access to the existing project Vault and Calendar.
+All calls use the server workload identity; the App cannot select a different
+App or project. These are runtime credentials, not deployment environment
+variables: saving or rotating one never starts a build.
+
+```ts
+const reference = { namespace: 'stripe_test', scope: 'hotel_1', name: 'api' };
+await sdk.credentials.store({ ...reference, value: serverSideInput });
+const { value } = await sdk.credentials.read(reference);
+// Use only in the server provider adapter; never return or log `value`.
+await sdk.credentials.remove(reference);
+
+await sdk.calendar.connect({
+  id: 'airbnb_room_1', scope: 'hotel_1', resourceId: 'room_1',
+  name: 'Airbnb', url: privateIcalUrl,
+});
+const snapshot = await sdk.calendar.snapshot({ id: 'airbnb_room_1', scope: 'hotel_1' });
+await sdk.calendar.upsert({
+  id: 'booking_1', scope: 'hotel_1', resourceId: 'room_1',
+  from: '2026-11-01', to: '2026-11-03', title: 'Reserved',
+  version: 1, active: true,
+});
+await sdk.jobs.ensure({
+  key: 'maintenance', path: '/api/internal/sync', everySeconds: 60,
+});
+```
+
+Calendar stores encrypted source URLs, validates whole Airbnb availability
+feeds and preserves the last snapshot after failure. Dates are civil days with
+an exclusive end. The export URL is a private bearer capability: show it only to
+authorized operators. Exports include the App's active projections, never
+imported blocks or guest data. Increasing versions and `active: false` tombstones
+prevent delayed retries from restoring cancelled intervals.
+
+The platform worker synchronizes sources independently of the App and invokes
+registered callbacks with Cloud Run identity and `X-NF-App-Call`, including
+after scale-to-zero. Verify the exact App, method, path and raw body with
+`verifyNightfuelCall`. Jobs are at-least-once; handlers must be idempotent and
+bounded. Integration requests and event emissions time out after 15 seconds.
+
+## Typed resources for Workflow Loader
+
+Apps can expose business objects independently of events. Publish the schema
+from server code; each version is immutable and every item has a required string
+`id`. The schema dialect and limits are the same as typed events.
+
+```ts
+import { defineAppResources, resourceSchema as s, createAppResourceHandler } from '@nightfuel-ai/app-sdk';
+import { mkdirSync, writeFileSync } from 'node:fs';
+
+export const resources = defineAppResources([{
+  key: 'kitchen.ingredient',
+  version: 1,
+  title: 'Ingredient',
+  item: s.object({
+    id: s.string({ minLength: 1 }),
+    name: s.string(),
+    quantity: s.number({ minimum: 0 }),
+    unit: s.enum('kg', 'l'),
+  }),
+}]);
+// In a generation script: commit this file with the App's source.
+mkdirSync('.nightfuel', { recursive: true });
+writeFileSync('.nightfuel/resources.json', JSON.stringify(resources.manifest, null, 2) + '\n');
+
+// In the App server. `policy` and `ingredients` are your own business adapters.
+const readResource = createAppResourceHandler(resources, {
+  authorize: ({ principal, itemId }) => policy.canReadIngredient(principal, itemId),
+  readers: [{
+    key: 'kitchen.ingredient', version: 1,
+    read: ({ itemId }) => ingredients.findPublicProjection(itemId), // typed item or null
+  }],
+});
+// Register before express.json() so signature verification receives exact bytes.
+app.post('/_nightfuel/resources/read', express.raw({ type: 'application/json', limit: '256kb' }), async (req, res) => {
+  try {
+    const reply = await readResource({
+      headers: req.headers, method: req.method, path: req.path, rawBody: req.body,
+    });
+    res.json(reply);
+  } catch (error) {
+    res.status(error.statusCode || error.status || 500).json({ error: 'Resource unavailable' });
+  }
+});
+```
+
+The handler uses server-only `NF_APP_ID` and `NF_APP_CALL_SECRET` supplied by
+the platform (or explicit `appId`/`secret` options). Do not include them in
+browser bundles. Resource reads use a separate signing purpose: an ordinary
+Apphook token, even for the same URL and body, is not sufficient.
+
+`authorize` is mandatory and runs before `read`. It receives the authenticated
+`principal: { type, id, workspaceId, projectId }`; types are `user`, `agent`,
+`workflow` and `mcp_connection`. A published workflow uses its own identity,
+not the publisher's. Implement record-level policy in the App: platform App
+visibility is only the first access check. Readers must have no side effects.
+
+Use `null` for authorized absence. Wrong IDs, undeclared fields, missing required
+fields and wrong types are rejected. The platform validates the response again.
+To change the schema, publish a new version and keep readers for old versions
+while workflows still use them. Discovery never calls the App or executes its
+code; normal source ingestion indexes the manifest for the native Loader and
+MCP catalog. Selecting a version pins its exact hash and never follows “latest”.
+
+The first contract supports one item by ID. It grants no arbitrary database
+querying, source access or automatic synchronization. Explicit workflows can map
+the result to native Pipeline Edit operations with `expectedRevision`.

package/events.d.ts

@@ -0,0 +1,59 @@
+declare const valueType: unique symbol;
+export interface EventSchema<T = unknown> {
+  readonly type: string;
+  readonly [valueType]?: T;
+}
+export type InferEventSchema<S> = S extends EventSchema<infer T> ? T : never;
+type OptionalKeys<P> = { [K in keyof P]: P[K] extends { readonly optional: true } ? K : never }[keyof P];
+type ObjectPayload<P> = {
+  [K in Exclude<keyof P, OptionalKeys<P>>]: InferEventSchema<P[K]>
+} & { [K in OptionalKeys<P>]?: InferEventSchema<P[K]> };
+export const eventSchema: {
+  string(options?: { description?: string; minLength?: number; maxLength?: number; format?: 'date' | 'date-time' | 'uuid' }): EventSchema<string>;
+  number(options?: { description?: string; minimum?: number; maximum?: number }): EventSchema<number>;
+  integer(options?: { description?: string; minimum?: number; maximum?: number }): EventSchema<number>;
+  boolean(): EventSchema<boolean>;
+  enum<const T extends readonly [string, ...string[]]>(...values: T): EventSchema<T[number]>;
+  enum<const T extends readonly [number, ...number[]]>(...values: T): EventSchema<T[number]>;
+  enum<const T extends readonly [boolean, ...boolean[]]>(...values: T): EventSchema<T[number]>;
+  enum(value: null): EventSchema<null>;
+  array<S extends EventSchema>(items: S, options?: { minItems?: number; maxItems?: number }): EventSchema<InferEventSchema<S>[]>;
+  optional<S extends EventSchema>(schema: S): S & { readonly optional: true };
+  object<const P extends Record<string, EventSchema>>(properties: P): EventSchema<ObjectPayload<P>>;
+};
+export interface AppEventDefinition {
+  version: number;
+  title?: string;
+  description?: string;
+  payload: EventSchema;
+}
+export type AppEventDefinitions = Record<string, AppEventDefinition>;
+export interface AppEventDescriptor {
+  key: string;
+  version: number;
+  title: string;
+  description: string;
+  payloadSchema: Record<string, unknown>;
+  contractHash: string;
+}
+export interface AppEventManifest {
+  schemaVersion: 'nightfuel.app-events.v1';
+  events: AppEventDescriptor[];
+}
+declare const definitionsType: unique symbol;
+export interface DefinedAppEvents<T extends AppEventDefinitions = AppEventDefinitions> {
+  readonly manifest: AppEventManifest;
+  readonly [definitionsType]?: T;
+}
+export type EventPayload<C, K extends string> = C extends DefinedAppEvents<infer D>
+  ? K extends keyof D ? InferEventSchema<D[K]['payload']> : never : never;
+export function defineAppEvents<const T extends AppEventDefinitions>(definitions: T): DefinedAppEvents<T>;
+export interface AppEventReceipt {
+  eventId: string;
+  status: 'accepted';
+  replay: boolean;
+}
+export interface AppEventClient<T extends AppEventDefinitions> {
+  emit<K extends keyof T & string>(key: K, payload: InferEventSchema<T[K]['payload']>,
+    options: { idempotencyKey: string; occurredAt: string }): Promise<AppEventReceipt>;
+}

package/events.js

@@ -0,0 +1,188 @@
+'use strict';
+
+// Shared by the SDK and the platform. A deliberately bounded JSON Schema
+// dialect keeps validation and TypeScript inference in agreement.
+const crypto = require('node:crypto');
+const MANIFEST_PATH = '.nightfuel/events.json';
+const SCHEMA_VERSION = 'nightfuel.app-events.v1';
+const MAX_BYTES = 256 * 1024;
+const FORBIDDEN = new Set(['__proto__', 'constructor', 'prototype']);
+const own = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+const plain = value => value && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const fail = (message, code = 'APP_EVENT_CONTRACT_INVALID') => {
+  throw Object.assign(new Error(message), { code, status: 400, statusCode: 400 });
+};
+function exact(value, keys, at) {
+  if (!plain(value)) fail(`${at} must be an object`);
+  for (const key of Object.keys(value)) if (FORBIDDEN.has(key) || !keys.includes(key)) fail(`${at}.${key} is unsupported`);
+}
+function canonical(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+}
+const digest = value => crypto.createHash('sha256').update(canonical(value)).digest('hex');
+function text(value, at, max, required = false) {
+  if (value === undefined && !required) return '';
+  if (typeof value !== 'string' || value.length > max || (required && !value.trim())) fail(`${at} must be text of at most ${max} characters`);
+  return value;
+}
+function normalizeSchema(value, depth = 0, budget = { nodes: 0 }) {
+  if (depth > 12 || ++budget.nodes > 1000) fail('Event schema is too complex');
+  exact(value, ['type', 'properties', 'required', 'additionalProperties', 'items', 'enum',
+    'description', 'minLength', 'maxLength', 'minimum', 'maximum', 'minItems', 'maxItems', 'format'], 'schema');
+  const schema = { type: value.type };
+  if (!['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'].includes(schema.type)) fail('Unsupported event field type');
+  if (value.description !== undefined) schema.description = text(value.description, 'description', 2000);
+  const allowed = new Set(['type', 'description']);
+  if (schema.type === 'object') {
+    ['properties', 'required', 'additionalProperties'].forEach(key => allowed.add(key));
+    if (!plain(value.properties) || value.additionalProperties !== false) fail('Event objects require properties and additionalProperties:false');
+    const required = value.required ?? [];
+    if (!Array.isArray(required) || new Set(required).size !== required.length
+      || required.some(key => typeof key !== 'string' || !own(value.properties, key))) fail('Invalid required event fields');
+    schema.properties = {};
+    for (const key of Object.keys(value.properties).sort()) {
+      if (FORBIDDEN.has(key) || !/^[A-Za-z_][A-Za-z0-9_]{0,79}$/.test(key)) fail(`Invalid event field: ${key}`);
+      schema.properties[key] = normalizeSchema(value.properties[key], depth + 1, budget);
+    }
+    schema.required = [...required].sort();
+    schema.additionalProperties = false;
+  } else if (schema.type === 'array') {
+    ['items', 'minItems', 'maxItems'].forEach(key => allowed.add(key));
+    schema.items = normalizeSchema(value.items, depth + 1, budget);
+  } else {
+    allowed.add('enum');
+    if (value.enum !== undefined) {
+      if (!Array.isArray(value.enum) || !value.enum.length || value.enum.length > 100
+        || value.enum.some(item => !scalarMatches(schema.type, item))
+        || new Set(value.enum.map(canonical)).size !== value.enum.length) fail('Invalid event enum');
+      schema.enum = [...value.enum];
+    }
+  }
+  const bounds = schema.type === 'string' ? ['minLength', 'maxLength']
+    : schema.type === 'array' ? ['minItems', 'maxItems']
+      : ['number', 'integer'].includes(schema.type) ? ['minimum', 'maximum'] : [];
+  for (const key of bounds) {
+    allowed.add(key);
+    if (value[key] === undefined) continue;
+    if (!Number.isFinite(value[key]) || (!['minimum', 'maximum'].includes(key) && (!Number.isInteger(value[key]) || value[key] < 0))) fail(`Invalid ${key}`);
+    schema[key] = value[key];
+  }
+  if (bounds.length && schema[bounds[0]] !== undefined && schema[bounds[1]] !== undefined
+    && schema[bounds[0]] > schema[bounds[1]]) fail('Event field bounds are reversed');
+  if (schema.type === 'string') {
+    allowed.add('format');
+    if (value.format !== undefined) {
+      if (!['date', 'date-time', 'uuid'].includes(value.format)) fail('Unsupported event string format');
+      schema.format = value.format;
+    }
+  }
+  for (const key of Object.keys(value)) if (!allowed.has(key)) fail(`${key} is not valid for ${schema.type}`);
+  return schema;
+}
+function scalarMatches(type, value) {
+  if (type === 'null') return value === null;
+  if (type === 'integer') return Number.isSafeInteger(value);
+  if (type === 'number') return typeof value === 'number' && Number.isFinite(value);
+  return typeof value === type;
+}
+function validFormat(format, value) {
+  if (format === 'uuid') return /^[a-f\d]{8}-[a-f\d]{4}-[1-8][a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/i.test(value);
+  if (format === 'date') return /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value))
+    && new Date(value).toISOString().slice(0, 10) === value;
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)
+    && validFormat('date', value.slice(0, 10)) && Number.isFinite(Date.parse(value));
+}
+function validatePayload(schema, value, at = 'payload') {
+  const reject = message => fail(`${at}: ${message}`, 'APP_EVENT_PAYLOAD_INVALID');
+  if (schema.type === 'object') {
+    if (!plain(value)) reject('expected object');
+    for (const key of schema.required) if (!own(value, key) || value[key] === undefined) reject(`missing ${key}`);
+    for (const key of Object.keys(value)) {
+      if (!own(schema.properties, key)) reject(`unknown field ${key}`);
+      // Optional TypeScript properties may be explicitly undefined; JSON
+      // omits them on the wire. Required properties were checked above.
+      if (value[key] === undefined) continue;
+      validatePayload(schema.properties[key], value[key], `${at}.${key}`);
+    }
+  } else if (schema.type === 'array') {
+    if (!Array.isArray(value)) reject('expected array');
+    if (value.length > (schema.maxItems ?? 10000) || value.length < (schema.minItems ?? 0)) reject('array length outside contract');
+    value.forEach((entry, index) => validatePayload(schema.items, entry, `${at}[${index}]`));
+  } else {
+    if (!scalarMatches(schema.type, value)) reject(`expected ${schema.type}`);
+    if (schema.enum && !schema.enum.some(entry => entry === value)) reject('value outside enum');
+    if (schema.type === 'string') {
+      if (value.length < (schema.minLength ?? 0) || value.length > (schema.maxLength ?? MAX_BYTES)) reject('text length outside contract');
+      if (schema.format && !validFormat(schema.format, value)) reject(`expected ${schema.format}`);
+    }
+    if (typeof value === 'number' && (value < (schema.minimum ?? -Infinity) || value > (schema.maximum ?? Infinity))) reject('number outside contract');
+  }
+  return value;
+}
+function normalizeManifest(value) {
+  exact(value, ['schemaVersion', 'events'], 'manifest');
+  if (value.schemaVersion !== SCHEMA_VERSION || !Array.isArray(value.events) || value.events.length > 100) fail('Invalid app event manifest');
+  if (Buffer.byteLength(JSON.stringify(value), 'utf8') > MAX_BYTES) fail('App event manifest exceeds 256 KiB');
+  const keys = new Set();
+  const events = value.events.map(event => {
+    exact(event, ['key', 'version', 'title', 'description', 'payloadSchema', 'contractHash'], 'event');
+    if (typeof event.key !== 'string' || !/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*){1,7}$/.test(event.key)
+      || event.key.length > 120 || keys.has(event.key)) fail('Event keys must be unique dotted paths');
+    keys.add(event.key);
+    if (!Number.isSafeInteger(event.version) || event.version < 1) fail('Event version must be a positive integer');
+    const payloadSchema = normalizeSchema(event.payloadSchema);
+    if (payloadSchema.type !== 'object') fail('An event payload must be an object');
+    const normalized = {
+      key: event.key, version: event.version,
+      title: text(event.title, 'event.title', 160) || event.key,
+      description: text(event.description, 'event.description', 2000), payloadSchema,
+    };
+    const contractHash = digest({ key: event.key, version: event.version, payloadSchema });
+    if (event.contractHash !== undefined && event.contractHash !== contractHash) fail('Event contract hash does not match its schema');
+    return { ...normalized, contractHash };
+  }).sort((a, b) => a.key.localeCompare(b.key));
+  return { schemaVersion: SCHEMA_VERSION, events };
+}
+function freeze(value) {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+}
+function defineAppEvents(definitions) {
+  if (!plain(definitions)) fail('Event definitions must be an object');
+  return freeze({ manifest: normalizeManifest({ schemaVersion: SCHEMA_VERSION,
+    events: Object.entries(definitions).map(([key, definition]) => {
+      exact(definition, ['version', 'title', 'description', 'payload'], `events.${key}`);
+      return { key, version: definition.version, title: definition.title, description: definition.description, payloadSchema: definition.payload };
+    }) }) });
+}
+const eventSchema = Object.freeze({
+  string: (options = {}) => ({ type: 'string', ...options }),
+  number: (options = {}) => ({ type: 'number', ...options }),
+  integer: (options = {}) => ({ type: 'integer', ...options }),
+  boolean: () => ({ type: 'boolean' }),
+  enum: (...values) => ({ type: values[0] === null ? 'null' : typeof values[0], enum: values }),
+  array: (items, options = {}) => ({ type: 'array', items, ...options }),
+  optional: schema => ({ ...schema, optional: true }),
+  object: properties => ({
+    type: 'object', additionalProperties: false,
+    required: Object.keys(properties).filter(key => properties[key].optional !== true),
+    properties: Object.fromEntries(Object.entries(properties).map(([key, value]) => {
+      const { optional, ...schema } = value;
+      return [key, schema];
+    })),
+  }),
+});
+function sampleFromSchema(schema) {
+  if (schema.enum) return schema.enum[0];
+  if (schema.type === 'object') return Object.fromEntries(Object.entries(schema.properties).map(([key, child]) => [key, sampleFromSchema(child)]));
+  if (schema.type === 'array') return [];
+  if (schema.type === 'boolean') return false;
+  if (['integer', 'number'].includes(schema.type)) return schema.minimum ?? 0;
+  if (schema.type === 'null') return null;
+  return '';
+}
+module.exports = { MANIFEST_PATH, SCHEMA_VERSION, MAX_BYTES, defineAppEvents, eventSchema,
+  normalizeManifest, normalizeSchema, validatePayload, sampleFromSchema, canonical, digest };

package/index.d.ts

@@ -1,3 +1,7 @@
+import type { AppEventClient, AppEventDefinitions, DefinedAppEvents } from './events';
+export { defineAppEvents, eventSchema } from './events';
+export type { AppEventClient, AppEventDefinitions, AppEventManifest, AppEventReceipt, DefinedAppEvents, EventPayload, InferEventSchema } from './events';
+
 export interface NightfuelAppSdkErrorOptions {
   status?: number;
   code?: string;
@@ -161,10 +165,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,
@@ -173,14 +184,39 @@ export interface NightfuelWorkflowClient {
   ): AsyncGenerator<NightfuelWorkflowEvent<T>, void, undefined>;
 }
 
-export interface NightfuelAppSdk {
+export interface NightfuelAppSdk<T extends AppEventDefinitions = Record<string, never>> {
   readonly appId: string;
+  /** Server-only credentials owned by this exact App; no access to other project keys. */
+  readonly credentials: {
+    store(input: AppCredentialReference & { value: string }): Promise<{ configured: true; reference: AppCredentialReference; vaultKeyId: string }>;
+    read(input: AppCredentialReference): Promise<{ value: string }>;
+    remove(input: AppCredentialReference): Promise<{ configured: false; reference: AppCredentialReference }>;
+  };
+  readonly calendar: {
+    connect(input: { id: string; scope: string; resourceId: string; name: string; url: string }): Promise<AppCalendarSource>;
+    snapshot(input: { id: string; scope: string; refresh?: boolean }): Promise<{ source: AppCalendarSource; blocks: AppCalendarBlock[]; revision: number }>;
+    remove(input: { id: string; scope: string }): Promise<{ removed: true }>;
+    upsert(input: { id: string; scope: string; resourceId: string; from: string; to: string; title: string; version: number; active: boolean }): Promise<{ saved: true; version: number }>;
+  };
+  /** Durable platform callbacks that wake a scaled-to-zero App using its signed call identity. */
+  readonly jobs: {
+    ensure(input: { key: string; path: string; everySeconds: number }): Promise<{ key: string; enabled: boolean; everySeconds: number }>;
+  };
   readonly data: NightfuelDataClient;
   readonly workflows: NightfuelWorkflowClient;
+  readonly events: AppEventClient<T>;
   createIdempotencyKey(): string;
 }
+export interface AppCredentialReference { namespace: string; scope: string; name: string }
+export interface AppCalendarBlock { id: string; from: string; to: string }
+export interface AppCalendarSource {
+  id: string; scope: string; resourceId: string; name: string; enabled: boolean;
+  status: 'pending' | 'ok' | 'error'; lastSyncedAt: string | null; error: string | null; exportUrl: string | null;
+}
 
-export function createNightfuelAppSdk(options?: NightfuelAppSdkOptions): NightfuelAppSdk;
+export function createNightfuelAppSdk<const T extends AppEventDefinitions = Record<string, never>>(
+  options?: NightfuelAppSdkOptions & { events?: DefinedAppEvents<T> }
+): NightfuelAppSdk<T>;
 
 /** The claims Nightfuel signs into an Apphook request. */
 export interface NightfuelCallClaims {
@@ -218,3 +254,5 @@ export function verifyNightfuelCall(input: {
   appId?: string;
   now?: number;
 }): NightfuelCallClaims;
+export { defineAppResources, resourceSchema, createAppResourceHandler } from './resources';
+export type { AppResourceDefinition, AppResourceDescriptor, AppResourceManifest, DefinedAppResources, AppResourcePrincipal, AppResourceReadContext, AppResourceReply } from './resources';

package/index.js

@@ -8,6 +8,9 @@
 
 const crypto = require('crypto');
 const { parseSseFrame, recoverableSseStream, terminalRunStatus } = require('./stream');
+const AppEvents = require('./events');
+const { defineAppEvents, eventSchema } = AppEvents;
+const { defineAppResources, resourceSchema, createAppResourceHandler } = require('./resources');
 
 const METADATA_IDENTITY_URL =
   'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity';
@@ -113,6 +116,7 @@ async function responsePayload(response) {
 }
 
 function createNightfuelAppSdk(options = {}) {
+  const eventManifest = options.events ? AppEvents.normalizeManifest(options.events.manifest) : null;
   requiredServerRuntime();
   const env = options.env || process.env;
   const fetchImpl = options.fetch || globalThis.fetch;
@@ -175,17 +179,33 @@ function createNightfuelAppSdk(options = {}) {
     return response;
   }
 
-  async function postJson(path, body, headers = {}) {
+  async function postJson(path, body, headers = {}, signal) {
     const response = await request(path, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', ...headers },
       body: JSON.stringify(body),
+      signal,
     });
     return responsePayload(response);
   }
+  const integrationRequest = (path, input) => postJson(`/internal/hosting/apps/${appId}/${path}`, input, {}, AbortSignal.timeout(15000));
 
   return Object.freeze({
     appId,
+    credentials: Object.freeze({
+      store: input => integrationRequest('credentials/store', input),
+      read: input => integrationRequest('credentials/read', input),
+      remove: input => integrationRequest('credentials/remove', input),
+    }),
+    calendar: Object.freeze({
+      connect: input => integrationRequest('calendar/connect', input),
+      snapshot: input => integrationRequest('calendar/snapshot', input),
+      remove: input => integrationRequest('calendar/remove', input),
+      upsert: input => integrationRequest('calendar/upsert', input),
+    }),
+    jobs: Object.freeze({
+      ensure: input => integrationRequest('jobs/ensure', input),
+    }),
     data: Object.freeze({
       query: (input) => postJson(`/internal/hosting/apps/${appId}/data/query`, input || {}),
       semantic: (input) => postJson(`/internal/hosting/apps/${appId}/data/semantic`, input || {}),
@@ -201,13 +221,30 @@ function createNightfuelAppSdk(options = {}) {
         );
       },
     }),
+    events: Object.freeze({
+      async emit(eventKey, payload, options = {}) {
+        const definition = eventManifest?.events.find(event => event.key === eventKey);
+        if (!definition) throw new NightfuelAppSdkError('Declare this event with defineAppEvents before emitting it', {
+          code: 'APP_EVENT_UNDECLARED',
+        });
+        const key = idempotencyKey(options.idempotencyKey);
+        AppEvents.validatePayload(definition.payloadSchema, payload);
+        AppEvents.validatePayload({ type: 'string', format: 'date-time' }, options.occurredAt, 'occurredAt');
+        const body = { eventKey, version: definition.version, contractHash: definition.contractHash,
+          occurredAt: options.occurredAt, payload };
+        if (Buffer.byteLength(JSON.stringify(body), 'utf8') > AppEvents.MAX_BYTES) {
+          throw new NightfuelAppSdkError('App event exceeds 256 KiB', { code: 'APP_EVENT_TOO_LARGE', status: 413 });
+        }
+        return postJson(`/internal/hosting/apps/${appId}/events`, body, { 'Idempotency-Key': key }, AbortSignal.timeout(15000));
+      },
+    }),
     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 },
+          { input, ...(options.customFields === undefined ? {} : { customFields: options.customFields }) },
           { 'Idempotency-Key': key }
         );
       },
@@ -324,6 +361,11 @@ function verifyNightfuelCall({ headers, method, path, rawBody, secret, appId, no
 }
 
 module.exports = {
+  defineAppResources,
+  resourceSchema,
+  createAppResourceHandler,
+  defineAppEvents,
+  eventSchema,
   NightfuelAppSdkError,
   createNightfuelAppSdk,
   terminalRunStatus,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightfuel-ai/app-sdk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Server-only Nightfuel SDK for a hosted App workload identity.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -14,6 +14,10 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "events.js",
+    "events.d.ts",
+    "resources.js",
+    "resources.d.ts",
     "stream.js",
     "README.md",
     "LICENSE"

package/resources.d.ts

@@ -0,0 +1,58 @@
+import type { EventSchema, InferEventSchema } from './events';
+export { eventSchema as resourceSchema } from './events';
+export interface AppResourceDefinition {
+  key: string;
+  version: number;
+  title?: string;
+  description?: string;
+  item: EventSchema<{ id: string }>;
+}
+export interface AppResourceDescriptor {
+  key: string;
+  version: number;
+  title: string;
+  description: string;
+  itemSchema: Record<string, unknown>;
+  contractHash: string;
+}
+export interface AppResourceManifest {
+  schemaVersion: 'nightfuel.app-resources.v1';
+  resources: AppResourceDescriptor[];
+}
+declare const definitionsType: unique symbol;
+export interface DefinedAppResources<T extends readonly AppResourceDefinition[] = readonly AppResourceDefinition[]> {
+  readonly manifest: AppResourceManifest;
+  readonly [definitionsType]?: T;
+}
+export interface AppResourcePrincipal {
+  type: 'user' | 'agent' | 'workflow' | 'mcp_connection';
+  id: string;
+  workspaceId: string;
+  projectId: string;
+}
+export interface AppResourceReadContext {
+  resource: AppResourceDescriptor;
+  itemId: string;
+  principal: AppResourcePrincipal;
+}
+type ResourceReader<D extends AppResourceDefinition> = D extends AppResourceDefinition ? {
+  key: D['key'];
+  version: D['version'];
+  read(context: AppResourceReadContext): Promise<InferEventSchema<D['item']> | null> | InferEventSchema<D['item']> | null;
+} : never;
+export interface AppResourceReply {
+  appId: string;
+  key: string;
+  version: number;
+  contractHash: string;
+  itemId: string;
+  found: boolean;
+  item: Record<string, unknown> | null;
+}
+export function defineAppResources<const T extends readonly AppResourceDefinition[]>(definitions: T): DefinedAppResources<T>;
+export function createAppResourceHandler<const T extends readonly AppResourceDefinition[]>(resources: DefinedAppResources<T>, options: {
+  authorize(context: AppResourceReadContext): boolean | Promise<boolean>;
+  readers: ResourceReader<T[number]>[];
+  secret?: string;
+  appId?: string;
+}): (request: { headers: Record<string, string | string[] | undefined>; method: string; path: string; rawBody: Uint8Array }) => Promise<AppResourceReply>;

package/resources.js

@@ -0,0 +1,125 @@
+'use strict';
+
+// The SDK and platform consume this same bounded schema dialect. Contracts are
+// metadata: discovering them never evaluates App code or starts its runtime.
+const Schema = require('./events');
+const MANIFEST_PATH = '.nightfuel/resources.json';
+const SCHEMA_VERSION = 'nightfuel.app-resources.v1';
+const READ_PATH = '/_nightfuel/resources/read';
+const MAX_BYTES = Schema.MAX_BYTES;
+function resourceCallSecret(secret) {
+  if (typeof secret !== 'string' || !secret) fail('App resource verification secret is unavailable', 503);
+  return require('node:crypto').createHmac('sha256', secret).update('nightfuel.app-resource-read.v1').digest('hex');
+}
+const plain = value => value && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+function fail(message, statusCode = 400, code = 'APP_RESOURCE_INVALID') {
+  throw Object.assign(new Error(message), { status: statusCode, statusCode, code });
+}
+function exact(value, keys, label) {
+  if (!plain(value) || Object.keys(value).some(key => !keys.includes(key))) fail(`Invalid ${label}`);
+}
+function text(value, label, max, required = false) {
+  if (value === undefined && !required) return '';
+  if (typeof value !== 'string' || value.length > max || (required && !value.trim())) fail(`Invalid ${label}`);
+  return value;
+}
+function normalizeManifest(value) {
+  exact(value, ['schemaVersion', 'resources'], 'App resource manifest');
+  if (value.schemaVersion !== SCHEMA_VERSION || !Array.isArray(value.resources) || value.resources.length > 100
+    || Buffer.byteLength(JSON.stringify(value)) > MAX_BYTES) fail('Invalid App resource manifest');
+  const identities = new Set();
+  const resources = value.resources.map(resource => {
+    exact(resource, ['key', 'version', 'title', 'description', 'itemSchema', 'contractHash'], 'resource');
+    if (typeof resource.key !== 'string' || !/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*){0,7}$/.test(resource.key)
+      || resource.key.length > 120 || !Number.isSafeInteger(resource.version) || resource.version < 1) fail('Invalid resource key or version');
+    const identity = `${resource.key}:${resource.version}`;
+    if (identities.has(identity)) fail('Duplicate resource key and version');
+    identities.add(identity);
+    const itemSchema = Schema.normalizeSchema(resource.itemSchema);
+    if (itemSchema.type !== 'object' || itemSchema.properties.id?.type !== 'string' || !itemSchema.required.includes('id')) {
+      fail('A resource item requires a string id field');
+    }
+    const contractHash = Schema.digest({ key: resource.key, version: resource.version, itemSchema });
+    if (resource.contractHash !== undefined && resource.contractHash !== contractHash) fail('Resource contract hash mismatch');
+    return { key: resource.key, version: resource.version,
+      title: text(resource.title, 'resource title', 160) || resource.key,
+      description: text(resource.description, 'resource description', 2000), itemSchema, contractHash };
+  }).sort((a, b) => a.key.localeCompare(b.key) || a.version - b.version);
+  return { schemaVersion: SCHEMA_VERSION, resources };
+}
+function freeze(value) {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+}
+function defineAppResources(definitions) {
+  if (!Array.isArray(definitions)) fail('Resource definitions must be an array');
+  return freeze({ manifest: normalizeManifest({ schemaVersion: SCHEMA_VERSION,
+    resources: definitions.map(definition => {
+      exact(definition, ['key', 'version', 'title', 'description', 'item'], 'resource definition');
+      return { key: definition.key, version: definition.version, title: definition.title,
+        description: definition.description, itemSchema: definition.item };
+    }) }) });
+}
+function validateItem(contract, itemId, item) {
+  if (item === null) return;
+  Schema.validatePayload(contract.itemSchema, item, 'item');
+  if (item.id !== itemId) fail('App returned another resource item', 502, 'APP_RESOURCE_ID_MISMATCH');
+}
+function validatePrincipal(principal) {
+  exact(principal, ['type', 'id', 'workspaceId', 'projectId'], 'resource principal');
+  if (!['user', 'agent', 'workflow', 'mcp_connection'].includes(principal.type)
+    || !/^[a-f\d]{24}$/i.test(principal.id || '')
+    || !/^[a-f\d]{24}$/i.test(principal.workspaceId || '')
+    || !/^[a-f\d]{24}$/i.test(principal.projectId || '')) fail('Invalid resource principal', 403);
+}
+function validateReply(contract, binding, value) {
+  exact(value, ['appId', 'key', 'version', 'contractHash', 'itemId', 'found', 'item'], 'resource reply');
+  for (const key of ['appId', 'key', 'version', 'contractHash', 'itemId']) {
+    if (value[key] !== binding[key]) fail('App resource reply does not match the requested contract', 502, 'APP_RESOURCE_REPLY_MISMATCH');
+  }
+  if (typeof value.found !== 'boolean' || value.found !== (value.item !== null)) fail('Invalid resource presence', 502);
+  if (Buffer.byteLength(JSON.stringify(value)) > MAX_BYTES) fail('App resource response is too large', 502);
+  validateItem(contract, binding.itemId, value.item);
+  return value;
+}
+
+// A framework-neutral handler for a raw POST body. Authorization is mandatory
+// and precedes record access. The App owns record-level policy; a schema or an
+// HTTP method alone cannot prove that arbitrary App code has no side effects.
+function createAppResourceHandler(resources, { authorize, readers, secret, appId } = {}) {
+  const manifest = normalizeManifest(resources?.manifest);
+  if (typeof authorize !== 'function' || !Array.isArray(readers)) fail('Resource authorization and readers are required');
+  const routes = new Map();
+  for (const reader of readers) {
+    const identity = `${reader.key}:${reader.version}`;
+    if (routes.has(identity) || typeof reader.read !== 'function'
+      || !manifest.resources.some(r => r.key === reader.key && r.version === reader.version)) fail('Invalid resource reader');
+    routes.set(identity, reader.read);
+  }
+  if (routes.size !== manifest.resources.length) fail('Every published resource version needs a reader');
+  return async request => {
+    if (request?.method !== 'POST' || request?.path !== READ_PATH
+      || !(request.rawBody instanceof Uint8Array) || request.rawBody.length > MAX_BYTES) fail('Invalid resource read request');
+    // Lazy require avoids the public SDK entrypoint's circular export.
+    // Generic Apphook tokens cannot assert a user/Agent identity. A separate
+    // signing purpose is required even if they address this same URL/body.
+    const claims = require('./index').verifyNightfuelCall({ ...request,
+      secret: resourceCallSecret(secret || process.env.NF_APP_CALL_SECRET), appId });
+    let input;
+    try { input = JSON.parse(Buffer.from(request.rawBody).toString('utf8')); } catch { fail('Invalid resource read JSON'); }
+    exact(input, ['appId', 'key', 'version', 'contractHash', 'itemId', 'principal'], 'resource read');
+    validatePrincipal(input.principal);
+    if (claims.appId !== input.appId || claims.projectId !== input.principal.projectId) fail('Resource principal scope mismatch', 403);
+    text(input.itemId, 'itemId', 512, true);
+    const contract = manifest.resources.find(r => r.key === input.key && r.version === input.version && r.contractHash === input.contractHash);
+    if (!contract) fail('The App does not serve this resource contract version', 409, 'APP_RESOURCE_VERSION_UNAVAILABLE');
+    const scope = freeze({ resource: contract, itemId: input.itemId, principal: input.principal });
+    if (await authorize(scope) !== true) fail('Resource item access denied', 403, 'APP_RESOURCE_ACCESS_DENIED');
+    const item = await routes.get(`${contract.key}:${contract.version}`)(scope);
+    return validateReply(contract, input, { appId: input.appId, key: contract.key, version: contract.version,
+      contractHash: contract.contractHash, itemId: input.itemId, found: item !== null, item });
+  };
+}
+module.exports = { MANIFEST_PATH, SCHEMA_VERSION, READ_PATH, MAX_BYTES, defineAppResources,
+  resourceSchema: Schema.eventSchema, normalizeManifest, validateItem, validateReply, createAppResourceHandler, resourceCallSecret };