@nightfuel-ai/app-sdk 0.3.0 → 0.6.0

package/README.md

@@ -300,3 +300,148 @@ 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/index.d.ts

@@ -1,4 +1,7 @@
 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';
 
@@ -185,7 +188,9 @@ export interface NightfuelWorkflowClient {
 }
 
 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 }>;
@@ -208,6 +213,22 @@ export interface NightfuelAppSdk<T extends AppEventDefinitions = Record<string,
   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;

package/index.js

@@ -11,6 +11,9 @@ const { parseSseFrame, recoverableSseStream, terminalRunStatus } = require('./st
 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';
@@ -191,7 +194,13 @@ function createNightfuelAppSdk(options = {}) {
   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),
@@ -361,6 +370,9 @@ function verifyNightfuelCall({ headers, method, path, rawBody, secret, appId, no
 }
 
 module.exports = {
+  verifyNightfuelMcpCall,
+  defineItemProjection,
+  createItemWriteHandler,
   defineAppResources,
   resourceSchema,
   createAppResourceHandler,

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.3.0",
+  "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,11 @@
   "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",