@nightfuel-ai/app-sdk 0.1.2 → 0.6.0

package/README.md

@@ -133,3 +133,315 @@ 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`.
+
+## Partial projection into native Items
+
+Use `items.sync` when a small, durable projection should appear in native Lists
+and Calendar even while the App is offline. Keep operational records in the
+App's database; do not copy a guest history or credentials into an Item.
+
+```ts
+import { createNightfuelAppSdk, defineItemProjection } from '@nightfuel-ai/app-sdk';
+const bookings = defineItemProjection({
+  key: 'bookings', title: 'Reservations', fields: {
+    state: { type: 'string', label: 'Status' },
+    arrival: { type: 'datetime', label: 'Stay', calendar: { endField: 'departure' } },
+    departure: { type: 'datetime', label: 'Departure' },
+    reference: { type: 'json', label: 'Reference' },
+  },
+});
+const sdk = createNightfuelAppSdk();
+await sdk.items.sync(bookings, {
+  scope: 'hotel_centro', id: 'booking_123', version: 2, title: 'Reservation ABC',
+  fields: {
+    state: 'confirmed', arrival: '2026-11-01T14:00:00-03:00',
+    departure: '2026-11-03T12:00:00-03:00', reference: { adults: 2 },
+  },
+});
+```
+
+The platform creates a native, project-local definition and collection per
+App/scope/key. The stable external ID binds exactly one native Item; callers
+cannot supply a project, pipeline or Item ID to overwrite another resource.
+Fields are typed as string, integer, number, boolean, date, datetime or JSON.
+Only datetime fields explicitly declaring a calendar interval appear in the
+Calendar. Dates nested in JSON do not become calendar events.
+
+Sync is a partial field update: omitted fields keep their values, `null` clears
+them. Extra native fields and tags are preserved. The App owns the title and
+declared fields; fields are read-only unless explicitly marked `editable: true`
+with a signed write handler (below). Business validation stays in the App. A new source version is required for every
+changed payload. Same-version retries are idempotent; older versions are ignored;
+same-version different contents return 409. Removing or disabling a native
+collection/Item does not silently recreate it. Contract changes and native
+definition drift return 409 and require an explicit migration.
+
+Persist a minimal snapshot in an outbox **in the same transaction as the domain
+change**, then sync after commit. The SDK rejects errors; it does not conceal
+failed deliveries. Keep the snapshot/version for retry, surface pending failures,
+and use `jobs.ensure` for callbacks that wake an App scaled to zero. State
+projections may coalesce newer versions; use On App events for every transition.
+
+`availability: { events: [{ id, resourceId, from, to }], replaceEventIds?: [] }`
+optionally supplies a full snapshot of date-only, exclusive-end intervals for
+existing iCal exports. Empty events clear them; omission leaves them alone. The
+platform writes these intervals and the Item atomically and renders only the Item
+in its Calendar. `replaceEventIds` explicitly adopts old `calendar.upsert` rows
+owned by the same App/scope. Imported external blocks are not re-exported.
+
+### Editing native Items through the App
+
+Declare `writePath: '/api/internal/items/write'`, `editable: true` on the selected
+fields, and optional `stages: [{ key, label, next: ['next_stage'] }]` in
+`defineItemProjection`. The first stage is initial; every sync must include a
+declared `stageKey` when stages exist. Only allowed transitions appear in the
+native contract. Fields and stage edits from the editor, REST, MCP and workflows
+use the same native mutation boundary.
+
+Register `createItemWriteHandler(definition, { authorize, write, secret?, appId? })`
+at `writePath` and pass the raw POST bytes, headers, method and path. `authorize`
+is mandatory: map the verified native principal to the App's explicit record and
+command policy. A native Item edit is not an App administrator login. The
+platform checks current Item edit permission, Item/container scope and App view
+scope before sending and on every durable retry. User roles are not copied.
+
+The typed writer receives `scope`, `id`, `expectedVersion`, `mutationId`,
+`principal` and `changes: { fields, stageKey? }`. Only editable field keys are
+inferred. Execute domain commands and store a receipt keyed by `mutationId`
+**in the same transaction**. Replays must return the exact receipt before
+checking the old source version. Return a canonical `ItemSyncInput` with a newer
+version, the complete authoritative projection and no private domain records.
+Use the same projection payload in the App outbox. The SDK validates the reply;
+the platform syncs it before acknowledging success. No local Item overwrite can
+bypass the App, including callers that forge an `origin` or request derived writes.
+
+Generic Apphook signatures cannot invoke this writer: it uses a separate HMAC
+purpose with the App's existing call secret. It is not necessary to create or
+store another API key. Native date Fields are converted from UTC-midnight
+serialization to civil `YYYY-MM-DD` values before reaching the writer.
+
+Only return `{ rejected: true, error: { code, message } }` with HTTP 400/403/404/409
+when the domain transaction definitively rejected the command. Bound error text
+is displayed to the editor. Timeouts, invalid responses and other HTTP failures
+remain pending. The platform persists the intent, retains the old Item until
+confirmation, and retries with the same mutation ID; HTTP invocation wakes a
+scaled-to-zero App. `APP_ITEM_WRITE_PENDING` tells the caller to refresh later.
+
+Save unrelated native fields/tags separately from App fields. Single-Item stage
+changes are supported; a multi-Item batch is rejected instead of claiming a
+distributed atomic transaction. Create records through the App/MCP: ordinary
+Item creation in a managed collection is rejected. Native version migrations
+and restores may preserve or extend local fields but cannot overwrite source
+fields. Deleted Items still require restoration before projection resumes.
+
+These contracts are immutable once a collection exists. An existing read-only
+projection needs an explicit contract/definition migration before enabling edits;
+changing only the App code does not silently unlock it.
+
+Collections inherit the App's attachment audience at creation; subsequent native
+ACL configuration stays authoritative for Item/Calendar readers. Each scope has
+its own collection, but App-local roles are not automatically mapped to NightFUEL
+roles. Configure native per-scope audiences before sharing data that requires
+different visibility. A projection grants no access to the App's full record.
+Requests are bounded to 32 fields, 64 KiB and 100 availability intervals.
+
+## Native MCP identity (0.6)
+
+Native App MCP transport signs each protocol request in `X-NF-App-Mcp`.
+Use `verifyNightfuelMcpCall({ headers, method, path, rawBody, appId, secret })`
+before looking up `claims.mcpConnectionId` in the App's explicit role bindings.
+The verifier binds the exact bytes, path, method, App, project, connection and
+expiry. Its signing purpose differs from generic `X-NF-App-Call`; a Call App
+workflow cannot impersonate a native MCP connection. Cloud Run transport IAM
+remains separate. Discovery carries the draft connection ID; execution uses the
+published connection ID and rechecks current NF authority on each request.
+Reject unbound, expired or revoked connections. Never grant admin by default.
+
+## Native map projections (0.6)
+
+`sdk.maps.sync({ scope, revision, title, pins, areas })` creates one native Map
+per App and scope. Pins contain `{ id, title, position: [longitude, latitude] }`;
+areas contain `{ id, title, ring, effect: 'allow' | 'deny' }`. Send a complete
+snapshot, increasing `revision` whenever its contents change. Retry the same
+revision and bytes after an uncertain response. The receipt contains `mapId`,
+`scope`, `revision`, `mapVersion` and `status` (created, updated or replay).
+
+Map, entities, version, binding and invalidation event commit together. Stale
+revisions, changed payloads at the same revision, deleted maps and native edits
+fail explicitly. The API cannot target arbitrary map IDs. Empty snapshots clear
+drawings. Limits: 2,000 drawings, 200 vertices per area and 512 KiB per request.
+Only send data appropriate for the App's NF project audience: App-local roles
+do not become native ACLs. Map attachments follow the App; the next sync applies
+attachment changes. A native attachment/content edit triggers a conflict.
+
+Before enabling this adapter on a platform installation, review and apply
+`node scripts/prepare_maps_indexes.js --apply` using the normal deployment
+procedure. Runtime checks the unique bindings; it never silently repairs missing
+production indexes. No deployment is performed by installing the SDK package.

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,10 @@
+import type { AppEventClient, AppEventDefinitions, DefinedAppEvents } from './events';
+import type { AppItemsClient } from './items';
+export { defineItemProjection, createItemWriteHandler } from './items';
+export type { ItemProjectionDefinition, ItemProjectionField, ItemProjectionValues, ItemSyncInput, ItemSyncReceipt, ItemJson, ItemWriteInput } from './items';
+export { defineAppEvents, eventSchema } from './events';
+export type { AppEventClient, AppEventDefinitions, AppEventManifest, AppEventReceipt, DefinedAppEvents, EventPayload, InferEventSchema } from './events';
+
 export interface NightfuelAppSdkErrorOptions {
   status?: number;
   code?: string;
@@ -180,14 +187,57 @@ export interface NightfuelWorkflowClient {
   ): AsyncGenerator<NightfuelWorkflowEvent<T>, void, undefined>;
 }
 
-export interface NightfuelAppSdk {
+export interface NightfuelAppSdk<T extends AppEventDefinitions = Record<string, never>> {
+  readonly maps: { sync(input: AppMapSync): Promise<AppMapReceipt> };
   readonly appId: string;
+  readonly items: AppItemsClient;
+  /** 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 AppMapSync {
+  scope: string; revision: number; title: string;
+  pins: Array<{ id: string; title: string; position: [number, number] }>;
+  areas: Array<{ id: string; title: string; ring: Array<[number, number]>; effect: 'allow' | 'deny' }>;
+}
+export interface AppMapReceipt {
+  mapId: string; scope: string; revision: number; mapVersion: number;
+  status: 'created' | 'updated' | 'replay';
+}
+export interface NightfuelMcpClaims extends NightfuelCallClaims { purpose: 'native_mcp'; mcpConnectionId: string }
+/** Only the native MCP transport can issue this purpose-separated proof. Bind its connection to local roles. */
+export function verifyNightfuelMcpCall(input: {
+  headers: Headers | Record<string, string | string[] | undefined>;
+  method: string; path: string; rawBody: string | Buffer;
+  secret?: string; appId?: string; projectId?: string; now?: number;
+}): NightfuelMcpClaims;
+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 {
@@ -225,3 +275,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,12 @@
 
 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 { defineItemProjection, validateItemSync } = require('./items');
+const { createItemWriteHandler } = require('./item-writes');
+const { verifyNightfuelMcpCall } = require('./mcp');
 
 const METADATA_IDENTITY_URL =
   'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity';
@@ -113,6 +119,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 +182,39 @@ 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({
+    maps: Object.freeze({ sync: input => integrationRequest('maps/sync', require('./maps').validateMapSync(input)) }),
     appId,
+    items: Object.freeze({
+      async sync(definition, input) {
+        return integrationRequest('items/sync', validateItemSync(definition, input));
+      },
+    }),
+    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,6 +230,23 @@ 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);
@@ -324,6 +370,14 @@ function verifyNightfuelCall({ headers, method, path, rawBody, secret, appId, no
 }
 
 module.exports = {
+  verifyNightfuelMcpCall,
+  defineItemProjection,
+  createItemWriteHandler,
+  defineAppResources,
+  resourceSchema,
+  createAppResourceHandler,
+  defineAppEvents,
+  eventSchema,
   NightfuelAppSdkError,
   createNightfuelAppSdk,
   terminalRunStatus,

package/item-writes.js

@@ -0,0 +1,57 @@
+'use strict';
+const crypto = require('crypto');
+const { defineItemProjection, validateItemSync } = require('./items');
+const fail = (message, statusCode = 400, code = 'APP_ITEM_WRITE_INVALID') => Object.assign(new Error(message), { statusCode, status: statusCode, code });
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  return value;
+}
+const digest = value => crypto.createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex');
+function exact(value, allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !allowed.includes(key))) throw fail('Invalid Item write object');
+}
+function itemWriteSecret(secret) {
+  if (typeof secret !== 'string' || secret.length < 32) throw fail('Item write secret unavailable', 503);
+  return crypto.createHmac('sha256', secret).update('nightfuel.app-item-write.v1').digest('hex');
+}
+function validateItemWrite(definitionInput, input) {
+  const definition = defineItemProjection(definitionInput);
+  if (!definition.writePath) throw fail('This projection does not accept edits');
+  exact(input, ['appId', 'key', 'contractHash', 'scope', 'id', 'expectedVersion', 'mutationId', 'principal', 'changes']);
+  if (input.key !== definition.key || input.contractHash !== digest(definition)) throw fail('App Item contract changed', 409, 'APP_ITEM_CONTRACT_CONFLICT');
+  if (!/^[a-f\d]{24}$/i.test(input.appId || '') || !/^[a-zA-Z0-9_-]{8,80}$/.test(input.mutationId || '')) throw fail('Invalid Item write identity');
+  exact(input.principal, ['type', 'id', 'projectId', 'workspaceId']);
+  if (!['user', 'agent', 'workflow', 'mcp_connection'].includes(input.principal.type) ||
+    ['id', 'projectId', 'workspaceId'].some(key => !/^[a-f\d]{24}$/i.test(input.principal[key] || ''))) throw fail('Invalid Item principal', 403);
+  exact(input.changes, ['fields', 'stageKey']);
+  const fields = input.changes.fields || {};
+  for (const key of Object.keys(fields)) if (!definition.fields[key]?.editable) throw fail(`Field ${key} is controlled by the App`);
+  const checked = validateItemSync(definition, { scope: input.scope, id: input.id, version: input.expectedVersion, title: 'Item edit', fields,
+    ...(definition.stages ? { stageKey: input.changes.stageKey ?? definition.stages[0].key } : {}) });
+  if (input.changes.stageKey !== undefined && !definition.stages) throw fail('This projection has no stages');
+  if (!Object.keys(fields).length && input.changes.stageKey === undefined) throw fail('An Item edit needs a change');
+  return { ...input, changes: { fields: checked.fields, ...(input.changes.stageKey !== undefined ? { stageKey: checked.stageKey } : {}) } };
+}
+function validateItemWriteReply(definition, input, result) {
+  const checked = validateItemSync(definition, result);
+  if (checked.id !== input.id || checked.scope !== input.scope || checked.version <= input.expectedVersion) throw fail('App reply does not match the edited Item', 502, 'APP_ITEM_WRITE_REPLY_INVALID');
+  const { definition: _, ...reply } = checked;
+  return reply;
+}
+function createItemWriteHandler(definitionInput, { authorize, write, secret, appId } = {}) {
+  const definition = defineItemProjection(definitionInput);
+  if (!definition.writePath || typeof authorize !== 'function' || typeof write !== 'function') throw fail('Item write handler requires explicit authorization and a writer');
+  return async request => {
+    if (request?.method !== 'POST' || request.path !== definition.writePath || !(request.rawBody instanceof Uint8Array) || request.rawBody.length > 65536) throw fail('Invalid Item write request');
+    // Generic Apphook signatures cannot delegate a user's Item permissions.
+    const claims = require('./index').verifyNightfuelCall({ ...request, secret: itemWriteSecret(secret || process.env.NF_APP_CALL_SECRET), appId });
+    let raw;
+    try { raw = JSON.parse(Buffer.from(request.rawBody).toString('utf8')); } catch { throw fail('Invalid Item write JSON'); }
+    const input = validateItemWrite(definition, raw);
+    if (claims.appId !== input.appId || claims.projectId !== input.principal.projectId) throw fail('Item principal scope mismatch', 403);
+    if (await authorize(input) !== true) throw fail('Item edit denied by the App', 403, 'APP_ITEM_WRITE_DENIED');
+    return validateItemWriteReply(definition, input, await write(input));
+  };
+}
+module.exports = { createItemWriteHandler, validateItemWrite, validateItemWriteReply, itemWriteSecret, digest };

package/items.d.ts

@@ -0,0 +1,66 @@
+export type ItemJson = null | boolean | number | string | ItemJson[] | { [key: string]: ItemJson };
+export interface ItemProjectionField {
+  type: 'string' | 'integer' | 'number' | 'boolean' | 'date' | 'datetime' | 'json';
+  label: string;
+  /** Native edits call the App's signed writer; never a local field overwrite. */
+  editable?: boolean;
+  calendar?: { endField: string };
+}
+export interface ItemProjectionDefinition {
+  key: string;
+  title: string;
+  fields: Readonly<Record<string, ItemProjectionField>>;
+  writePath?: string;
+  stages?: readonly { key: string; label: string; next: readonly string[] }[];
+}
+type FieldValue<F extends ItemProjectionField> = F['type'] extends 'json' ? ItemJson
+  : F['type'] extends 'integer' | 'number' ? number | null
+  : F['type'] extends 'boolean' ? boolean | null : string | null;
+export type ItemProjectionValues<D extends ItemProjectionDefinition> = { [K in keyof D['fields']]?: FieldValue<D['fields'][K]> };
+export interface ItemSyncInput<D extends ItemProjectionDefinition> {
+  scope: string;
+  id: string;
+  /** Monotonic source version. Retry with exactly the same payload and version. */
+  version: number;
+  title: string;
+  /** Omitted fields are preserved; null clears a field. */
+  fields: ItemProjectionValues<D>;
+  stageKey?: D extends { stages: readonly { key: infer K extends string }[] } ? K : string;
+  /** Optional full snapshot for iCal export; native Calendar renders the Item's date fields. */
+  availability?: {
+    events: { id: string; resourceId: string; from: string; to: string }[];
+    /** Adopt explicitly named legacy calendar.upsert events from this App/scope. */
+    replaceEventIds?: string[];
+  };
+}
+export interface ItemSyncReceipt {
+  itemId: string;
+  pipelineId: string;
+  version: number;
+  status: 'created' | 'updated' | 'replay' | 'stale';
+}
+export interface AppItemsClient {
+  sync<const D extends ItemProjectionDefinition>(definition: D, input: ItemSyncInput<NoInfer<D>>): Promise<ItemSyncReceipt>;
+}
+export function defineItemProjection<const D extends ItemProjectionDefinition>(definition: D): D;
+export interface ItemWriteInput<D extends ItemProjectionDefinition> {
+  appId: string;
+  key: D['key'];
+  contractHash: string;
+  scope: string;
+  id: string;
+  expectedVersion: number;
+  /** Persist a receipt atomically with the domain change; retries reuse this ID. */
+  mutationId: string;
+  principal: { type: 'user' | 'agent' | 'workflow' | 'mcp_connection'; id: string; projectId: string; workspaceId: string };
+  changes: {
+    fields: { [K in keyof D['fields'] as D['fields'][K] extends { editable: true } ? K : never]?: FieldValue<D['fields'][K]> };
+    stageKey?: ItemSyncInput<D>['stageKey'];
+  };
+}
+export function createItemWriteHandler<const D extends ItemProjectionDefinition>(definition: D, options: {
+  authorize(input: ItemWriteInput<NoInfer<D>>): boolean | Promise<boolean>;
+  write(input: ItemWriteInput<NoInfer<D>>): Promise<ItemSyncInput<NoInfer<D>>>;
+  secret?: string;
+  appId?: string;
+}): (request: { method: string; path: string; rawBody: Uint8Array; headers: Record<string, string | string[] | undefined> }) => Promise<ItemSyncInput<D>>;

package/items.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const TYPES = new Set(['string', 'integer', 'number', 'boolean', 'date', 'datetime', 'json']);
+const fail = message => Object.assign(new Error(message), { status: 400, statusCode: 400, code: 'APP_ITEM_INPUT_INVALID' });
+function object(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw fail(`${name} must be an object`);
+  return value;
+}
+function keys(value, allowed, name) {
+  object(value, name);
+  if (Object.keys(value).some(key => !allowed.includes(key))) throw fail(`${name} contains an undeclared property`);
+}
+function part(value, name) {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(value)) throw fail(`${name} is invalid`);
+  return value;
+}
+function label(value, name) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 160) throw fail(`${name} is invalid`);
+  return value.trim();
+}
+function json(value, depth = 0) {
+  if (depth > 12) throw fail('JSON is too deeply nested');
+  if (value === null || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value))) return value;
+  if (Array.isArray(value)) return value.map(entry => json(entry, depth + 1));
+  object(value, 'JSON');
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, json(entry, depth + 1)]));
+}
+function date(value) {
+  return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+}
+function defineItemProjection(input) {
+  keys(input, ['key', 'title', 'fields', 'stages', 'writePath'], 'projection');
+  const key = part(input.key, 'projection.key');
+  if (!/^[a-z][a-z0-9_]{0,63}$/.test(key)) throw fail('projection.key must be a lowercase Item type key');
+  const title = label(input.title, 'projection.title');
+  object(input.fields, 'projection.fields');
+  const entries = Object.entries(input.fields);
+  if (!entries.length || entries.length > 32) throw fail('A projection needs 1 to 32 fields');
+  const fields = Object.fromEntries(entries.map(([key, field]) => {
+    if (!/^[a-z][a-z0-9_]{0,63}$/.test(key) || ['constructor', 'prototype', '__proto__'].includes(key)) throw fail('Field key is invalid');
+    keys(field, ['type', 'label', 'calendar', 'editable'], key);
+    if (!TYPES.has(field.type)) throw fail(`Unsupported type for ${key}`);
+    const result = { type: field.type, label: label(field.label, key) };
+    if (field.editable !== undefined) {
+      if (typeof field.editable !== 'boolean') throw fail('editable must be a boolean');
+      result.editable = field.editable;
+    }
+    if (field.calendar !== undefined) {
+      keys(field.calendar, ['endField'], `${key}.calendar`);
+      if (field.type !== 'datetime' || field.calendar.endField === key || input.fields[field.calendar.endField]?.type !== 'datetime') throw fail('Calendar intervals need two different datetime fields');
+      result.calendar = Object.freeze({ endField: field.calendar.endField });
+    }
+    return [key, Object.freeze(result)];
+  }));
+  const result = { key, title, fields: Object.freeze(fields) };
+  if (input.writePath !== undefined) {
+    if (typeof input.writePath !== 'string' || !/^\/api\/internal\/[a-zA-Z0-9/_-]{1,180}$/.test(input.writePath)) throw fail('writePath must be an internal API path');
+    result.writePath = input.writePath;
+  }
+  if (entries.some(([, field]) => field.editable) && !result.writePath) throw fail('Editable fields require writePath');
+  if (input.stages !== undefined) {
+    if (!Array.isArray(input.stages) || !input.stages.length || input.stages.length > 32) throw fail('stages needs 1 to 32 entries');
+    const stageKeys = new Set(input.stages.map(stage => stage.key));
+    if (stageKeys.size !== input.stages.length) throw fail('Duplicate stage key');
+    result.stages = Object.freeze(input.stages.map(stage => {
+      keys(stage, ['key', 'label', 'next'], 'stage');
+      if (!/^[a-z][a-z0-9_]{0,63}$/.test(stage.key)) throw fail('Invalid stage key');
+      if (!Array.isArray(stage.next) || stage.next.some(key => !stageKeys.has(key) || key === stage.key) || new Set(stage.next).size !== stage.next.length) throw fail('Invalid stage transitions');
+      return Object.freeze({ key: stage.key, label: label(stage.label, 'stage.label'), next: Object.freeze([...stage.next]) });
+    }));
+  }
+  return Object.freeze(result);
+}
+function validateItemSync(definitionInput, input) {
+  const definition = defineItemProjection(definitionInput);
+  keys(input, ['scope', 'id', 'version', 'title', 'fields', 'availability', 'stageKey'], 'sync');
+  const result = { definition, scope: part(input.scope, 'scope'), id: part(input.id, 'id'), version: input.version, title: label(input.title, 'title') };
+  if (!Number.isSafeInteger(input.version) || input.version < 1) throw fail('version must be a positive safe integer');
+  if (definition.stages) {
+    if (!definition.stages.some(stage => stage.key === input.stageKey)) throw fail('stageKey must identify a declared stage');
+    result.stageKey = input.stageKey;
+  } else if (input.stageKey !== undefined) throw fail('This projection has no stages');
+  object(input.fields, 'fields');
+  result.fields = Object.fromEntries(Object.entries(input.fields).map(([key, value]) => {
+    const field = Object.prototype.hasOwnProperty.call(definition.fields, key) ? definition.fields[key] : null;
+    if (!field) throw fail(`Undeclared field: ${key}`);
+    const valid = value === null || (field.type === 'string' && typeof value === 'string' && value.length <= 8000)
+      || (field.type === 'integer' && Number.isSafeInteger(value)) || (field.type === 'number' && Number.isFinite(value))
+      || (field.type === 'boolean' && typeof value === 'boolean') || (field.type === 'date' && date(value))
+      || (field.type === 'datetime' && typeof value === 'string' && date(value.slice(0, 10))
+        && /^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.test(value) && Number.isFinite(Date.parse(value)))
+      || field.type === 'json';
+    if (!valid) throw fail(`Invalid value for ${key}`);
+    return [key, json(value)];
+  }));
+  if (input.availability !== undefined) {
+    keys(input.availability, ['events', 'replaceEventIds'], 'availability');
+    if (!Array.isArray(input.availability.events) || input.availability.events.length > 100) throw fail('availability.events must have at most 100 intervals');
+    const events = input.availability.events.map(event => {
+      keys(event, ['id', 'resourceId', 'from', 'to'], 'availability event');
+      if (!date(event.from) || !date(event.to) || event.from >= event.to) throw fail('Availability dates must form a nonempty, exclusive-end interval');
+      return { id: part(event.id, 'event.id'), resourceId: part(event.resourceId, 'resourceId'), from: event.from, to: event.to };
+    });
+    if (new Set(events.map(event => event.id)).size !== events.length) throw fail('Duplicate availability event');
+    const replaceEventIds = input.availability.replaceEventIds ?? [];
+    if (!Array.isArray(replaceEventIds) || replaceEventIds.length > 100) throw fail('replaceEventIds is invalid');
+    result.availability = { events, replaceEventIds: replaceEventIds.map(value => part(value, 'replaceEventIds')) };
+  }
+  if (Buffer.byteLength(JSON.stringify(result), 'utf8') > 65536) throw fail('Item projection exceeds 64 KiB');
+  return result;
+}
+module.exports = { defineItemProjection, validateItemSync };

package/maps.js

@@ -0,0 +1,36 @@
+'use strict';
+const fail = message => Object.assign(new Error(message), { status: 400, statusCode: 400, code: 'APP_MAP_INPUT_INVALID' });
+function object(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) throw fail(`${label} has unsupported fields`);
+}
+function text(value, max, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > max) throw fail(`${label} is invalid`);
+  return value.trim();
+}
+function key(value, label) {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9][\w-]{0,79}$/.test(value)) throw fail(`${label} is invalid`);
+  return value;
+}
+function point(value) {
+  if (!Array.isArray(value) || value.length !== 2 || !value.every(Number.isFinite) || Math.abs(value[0]) > 180 || Math.abs(value[1]) > 85) throw fail('Position must be [longitude, latitude]');
+  return [...value];
+}
+function validateMapSync(input) {
+  object(input, ['scope', 'revision', 'title', 'pins', 'areas'], 'Map projection');
+  if (!Number.isSafeInteger(input.revision) || input.revision < 1) throw fail('revision must be a positive safe integer');
+  if (!Array.isArray(input.pins) || !Array.isArray(input.areas) || input.pins.length + input.areas.length > 2000) throw fail('A map supports at most 2000 drawings');
+  const pins = input.pins.map(p => {
+    object(p, ['id', 'title', 'position'], 'Pin');
+    return { id: key(p.id, 'Pin id'), title: text(p.title, 160, 'Pin title'), position: point(p.position) };
+  });
+  const areas = input.areas.map(a => {
+    object(a, ['id', 'title', 'ring', 'effect'], 'Area');
+    if (!Array.isArray(a.ring) || a.ring.length < 3 || a.ring.length > 200 || !['allow', 'deny'].includes(a.effect)) throw fail('Area geometry or effect is invalid');
+    return { id: key(a.id, 'Area id'), title: text(a.title, 160, 'Area title'), ring: a.ring.map(point), effect: a.effect };
+  });
+  if (new Set(pins.map(p => p.id)).size !== pins.length || new Set(areas.map(a => a.id)).size !== areas.length) throw fail('Drawing ids must be unique within each kind');
+  const result = { scope: key(input.scope, 'scope'), revision: input.revision, title: text(input.title, 160, 'title'), pins, areas };
+  if (Buffer.byteLength(JSON.stringify(result)) > 524288) throw fail('Map projection exceeds 512 KiB');
+  return result;
+}
+module.exports = { validateMapSync };

package/mcp.js

@@ -0,0 +1,25 @@
+'use strict';
+const crypto = require('crypto');
+const MCP_CALL_HEADER = 'X-NF-App-Mcp';
+const PURPOSE = 'native_mcp';
+function mcpCallSecret(secret) {
+  if (!secret) throw Object.assign(new Error('NF_APP_CALL_SECRET is required'), { status: 503, code: 'NIGHTFUEL_APP_CALL_SECRET_MISSING' });
+  return crypto.createHmac('sha256', String(secret)).update('nightfuel-app-mcp:v1').digest('hex');
+}
+function verifyNightfuelMcpCall(input = {}) {
+  const { headers, method, path, rawBody, projectId, ...options } = input;
+  const appId = String(options.appId || process.env.NF_APP_ID || '');
+  const fail = () => Object.assign(new Error('Native MCP identity is invalid'), { status: 401, code: 'NIGHTFUEL_APP_MCP_TOKEN_INVALID' });
+  if (!/^[a-f0-9]{24}$/i.test(appId) || !method || !path || rawBody === undefined) throw fail();
+  const token = typeof headers?.get === 'function' ? headers.get(MCP_CALL_HEADER)
+    : headers?.[Object.keys(headers || {}).find(key => key.toLowerCase() === MCP_CALL_HEADER.toLowerCase())];
+  if (typeof token !== 'string') throw fail();
+  const claims = require('./index').verifyNightfuelCall({ ...options, appId, method, path, rawBody,
+    headers: { 'x-nf-app-call': token }, secret: mcpCallSecret(options.secret || process.env.NF_APP_CALL_SECRET) });
+  if (claims.purpose !== PURPOSE || !/^[a-f0-9]{24}$/.test(claims.mcpConnectionId || '')
+      || !/^[a-f0-9]{24}$/.test(claims.projectId || '') || (projectId && projectId !== claims.projectId)
+      || !Number.isFinite(claims.iat) || !Number.isFinite(claims.exp)
+      || claims.exp <= claims.iat || claims.exp - claims.iat > 300000) throw fail();
+  return claims;
+}
+module.exports = { MCP_CALL_HEADER, PURPOSE, mcpCallSecret, verifyNightfuelMcpCall };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightfuel-ai/app-sdk",
-  "version": "0.1.2",
+  "version": "0.6.0",
   "description": "Server-only Nightfuel SDK for a hosted App workload identity.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -14,6 +14,15 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "maps.js",
+    "mcp.js",
+    "items.js",
+    "item-writes.js",
+    "items.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 };