@enc-protocol/flow -- SDK API Reference

npm config set @enc-protocol:registry https://npm-registry.ocrybit.workers.dev/
npm install @enc-protocol/flow

import {
  extractSchema,
  deriveManifest,
  deriveManifestFromSchema,  // schema-first entry point (no UI/flow needed)
  match,
  generate,
  profileEnclave,
  deriveFlow,
  createSDK,
  FLOW_CONFIG,               // inline fallback (browser-safe)
  loadFlowConfig,            // async Node-only loader for per-app flow.json
} from '@enc-protocol/flow'

ui.json + flow.json  ─►  schema.json  ─►  app.json  ─►  infra.json
                                          enclaves/*.json ─┘

interface Schema {
  id: string                              // App identifier
  name: string                            // Display name
  data_types: Record<string, JSONSchema>  // Write tables with JSON Schema
  actions: Record<string, ActionDef>      // Named write triggers
  reads: Record<string, ReadSpec>         // Read subscriptions
  encrypt: string[]                       // Encrypted table names
  // Absorbed from flow (only present if flow set them):
  tableMap?: Record<string, string>       // UI table -> enclave event
  derived?: string[]                      // Client-side view tables
  enclaves?: string | string[]            // Enclave override ('*' or list)
  sources?: { protocol?: string[]; external?: string[] }
  external?: {                            // Only if app has external data
    reads: Record<string, { fields: string[] }>
    writes: Record<string, JSONSchema>
  }
}
 
interface ActionDef {
  write?: string       // Target table (for insert)
  delete?: string      // Target table (for delete)
  page: string         // Source page path
  trigger: string      // UI trigger (e.g., '#bar.submit')
}
 
interface ReadSpec {
  fields: string[]        // Column names referenced
  cross_enclave?: boolean // True if table is read-only (not written)
}

import { extractSchema } from '@enc-protocol/flow'
 
const schema = extractSchema(helloApp)
// {
//   id: 'hello',
//   name: 'Hello',
//   data_types: {
//     messages: {
//       type: 'object',
//       properties: { draft: { type: 'string' } },
//       required: ['draft']
//     }
//   },
//   actions: {
//     feed_bar_submit: { write: 'messages', page: '/feed', trigger: '#bar.submit' },
//     my_posts_bar_submit: { write: 'messages', page: '/my_posts', trigger: '#bar.submit' }
//   },
//   reads: {
//     messages: { fields: ['from', 'body', 'trailing'] }
//   },
//   encrypt: []
// }

interface EnclaveProfile {
  name: string                // Enclave name
  parties: '1' | '2' | 'N'   // Participant model
  readerModel: 'public' | 'member' | 'owner'
  events: Record<string, EventProfile>
  stateCount: number          // Number of states in the enclave
}
 
interface EventProfile {
  write: boolean              // Has Create permission (non-dataview)
  dataviewP: boolean          // Has Poll permission
  operators: string[]         // All operators for this event
}

import { profileEnclave } from '@enc-protocol/flow'
 
const helloManifest = {
  states: [],
  traits: ['owner(0)', 'dataview(1)'],
  readers: [{ type: 'Public', reads: '*' }],
  moves: [],
  customs: [
    { event: 'post', operator: 'owner', ops: ['C', 'U', 'D'] },
    { event: 'post', operator: 'dataview', ops: ['P'] }
  ],
  // ...
}
 
const profile = profileEnclave('Hello', helloManifest)
// {
//   name: 'Hello',
//   parties: '1',
//   readerModel: 'public',
//   events: {
//     post: { write: true, dataviewP: true, operators: ['owner', 'dataview'] }
//   },
//   stateCount: 0
// }

interface MatchResult {
  primary: { name: string, score: number, profile: EnclaveProfile } | null
  crossEnclave: CrossEnclaveRead[]
  enclaves: string[]           // All enclaves needed
  scores: { name: string, score: number, profile: EnclaveProfile }[]  // Top 6
  profiles: Record<string, EnclaveProfile>
}
 
interface CrossEnclaveRead {
  table: string                // Read-only table name
  enclave: string              // Source enclave name
  event: string                // Source event name
  reason: string               // Human-readable reason
}

Score = 0
 
// Write coverage: min(writableEvents, writeTableCount) * 10
// Read coverage: min(totalEvents, totalTableCount) * 3
// Excess events penalty: -(totalEvents - totalTableCount) * 2  (if > 2x)
// Insufficient events: -(writeTableCount - writableEvents) * 5
 
// Encrypted writes need owner/member reader: +10
// Encrypted writes with public reader: -10
// Plaintext writes with DataView P or public: +5
 
// Disqualified: writeTableCount > 0 but writableEvents == 0

import { match, extractSchema } from '@enc-protocol/flow'
 
const schema = extractSchema(helloApp)
const result = match(schema, {
  Hello: { manifest: helloEnclave.manifest },
  DM: { manifest: dmEnclave.manifest },
  Timeline: { manifest: timelineEnclave.manifest },
})
// {
//   primary: { name: 'Hello', score: 23, profile: { ... } },
//   crossEnclave: [],
//   enclaves: ['Hello'],
//   scores: [
//     { name: 'Hello', score: 23 },
//     { name: 'Timeline', score: 15 },
//     ...
//   ],
//   profiles: { Hello: { ... }, DM: { ... }, ... }
// }

interface GeneratedEnclave {
  name: string                     // schema.name or schema.id
  description: string              // Auto-generated description
  manifest: {
    states: []                     // Always empty (1-party)
    traits: string[]               // ['owner(0)'] + optionally ['dataview(1)']
    readers: ReaderRule[]          // Owner-only or Public
    moves: []                      // Always empty
    grants: GrantRule[]            // DataView grants if needed
    transfers: []                  // Always empty
    slots: []                      // Always empty
    lifecycle: LifecycleRule[]     // Always includes Terminate
    customs: CustomRule[]          // One per data type
    init: InitRule[]               // Owner initialization
  }
  encryption: Record<string, { algorithm: string }>  // Per encrypted event
  data_types: Record<string, JSONSchema>             // Passthrough from schema
}

import { generate, extractSchema } from '@enc-protocol/flow'
 
const schema = extractSchema(helloApp)
const enclave = generate(schema)
// {
//   name: 'Hello',
//   description: 'Auto-generated enclave for Hello.',
//   manifest: {
//     states: [],
//     traits: ['owner(0)', 'dataview(1)'],
//     readers: [{ type: 'Public', reads: '*' }],
//     customs: [
//       { event: 'message', operator: 'OWNER', ops: ['C', 'U', 'D'] },
//       { event: 'message', operator: 'dataview', ops: ['P'] }
//     ],
//     ...
//   },
//   encryption: {},
//   data_types: { messages: { ... } }
// }

interface AppManifest {
  id: string
  name: string
  version: '1.0.0'
  enclaves: string[]
  data_types: Record<string, Record<string, string | ColSpec>>
  cross_enclave_reads?: Record<string, CrossRead>
}
 
interface ColSpec {
  type: string
  encrypted?: boolean
  optional?: boolean
}
 
interface CrossRead {
  enclave: string
  event: string
  access: 'read'
}

{
  wallet:     ['DM'],
  appstore:   ['*'],
  super:      ['DM', 'Group', 'Personal'],
  node:       ['*'],
  mini_hello: ['Hello'],
}

import { deriveManifest } from '@enc-protocol/flow'
 
const manifest = deriveManifest(helloApp, enclaveRegistry)
// {
//   id: 'hello',
//   name: 'Hello',
//   version: '1.0.0',
//   enclaves: ['Hello'],
//   data_types: { messages: { draft: 'string' } }
// }
 
const dmManifest = deriveManifest(dmApp, enclaveRegistry)
// {
//   id: 'dm',
//   name: 'DM',
//   version: '1.0.0',
//   enclaves: ['DM', 'Registry'],
//   data_types: { invites: {}, contacts: {}, messages: { message_draft: 'string' } },
//   cross_enclave_reads: {
//     profiles: { enclave: 'Registry', event: 'reg_identity', access: 'read' }
//   }
// }

interface SDK {
  // Dynamically generated per infra.json commands:
  submit_<eventName>: (content: any, cryptoOpts?: any) => Promise<any>
 
  // Dynamically generated per infra.json endpoints:
  query_<endpointName>: (opts?: any) => Promise<any[]>
 
  // Fixed methods:
  subscribe: (callback: (event: any) => void) => () => void
  query_events: (eventType: string, opts?: any) => Promise<any[]>
  create_enclave: (rbac: any) => Promise<any>
 
  // Cross-enclave:
  registry: {
    setAdapter: (adapter: any) => void
    publish: (identity: any) => Promise<any>
    lookup: (pubKey: string) => Promise<any>
    nameFor: (pubKey: string) => string
    _adapter: any
    _cache: Map<string, any>
  }
 
  // External data:
  external: {
    register: (name: string, fetchFn: Function) => void
    fetch: (name: string, opts?: any) => Promise<any>
    _handlers: Map<string, Function>
  }
 
  // Metadata:
  _adapter: any
  _appId: string
  _infra: object
  _events: string[]           // Commit event names
  _queries: string[]          // Query endpoint names
  _encrypted: string[]        // Encrypted table names
  _externalTables: string[]   // External table names
  crypto: object | null       // Injected crypto hooks
}

import { createSDK } from '@enc-protocol/flow'
 
// Basic plaintext app
const sdk = createSDK('hello', infraJson, pureAdapter)
await sdk.submit_post({ body: 'Hello World', from: '79be...' })
const rows = await sdk.query_messages({ limit: 50 })
const unsub = sdk.subscribe(event => console.log(event.content))
 
// Encrypted app with crypto
const dmSdk = createSDK('dm', dmInfra, adapter, {
  crypto: {
    encrypt: async (eventName, content) => {
      return ecdhEncrypt(content, recipientPub)
    },
    decrypt: async (eventName, encContent, senderPub) => {
      return ecdhDecrypt(encContent, senderPub)
    },
  }
})
await dmSdk.submit_message({ body: 'secret' })  // auto-encrypts
 
// Cross-enclave identity
sdk.registry.setAdapter(registryAdapter)
await sdk.registry.publish({ id_pub: '79be...', display_name: 'Alice' })
const identity = await sdk.registry.lookup('79be...')
const name = sdk.registry.nameFor('79be...')  // 'Alice' (from cache)

interface MethodDef {
  name: string        // e.g., 'submit_post', 'query_messages'
  type: 'write' | 'read' | 'subscribe' | 'lifecycle'
  event?: string      // For write methods: event name
  encrypted?: boolean // For write methods: whether event is encrypted
  method?: string     // For read methods: HTTP method
  path?: string       // For read methods: endpoint path
}

import { sdkMethods } from '@enc-protocol/flow/sdk-gen'
 
const methods = sdkMethods('hello', helloInfra)
// [
//   { name: 'submit_post', type: 'write', event: 'post', encrypted: false },
//   { name: 'query_messages', type: 'read', method: 'GET', path: '/messages' },
//   { name: 'subscribe', type: 'subscribe' },
//   { name: 'query_events', type: 'read' },
//   { name: 'create_enclave', type: 'lifecycle' },
// ]

interface FlowConfigEntry {
  tableMap?: Record<string, string>     // UI table -> enclave event
  encrypt?: string[]                    // Encrypted tables
  derived?: string[]                    // Client-side view tables
  sources?: {
    protocol?: string[]                 // Protocol-backed tables
    external?: string[]                 // External API-backed tables
  }
  enclaves?: string | string[]         // Explicit enclave(s) or '*'
}

import { FLOW_CONFIG } from '@enc-protocol/flow'
 
// Access a specific app's config
const helloConfig = FLOW_CONFIG.hello
// { tableMap: { messages: 'post', my_messages: 'post' }, derived: ['my_messages'] }
 
// Check if a table is encrypted
const isEncrypted = (FLOW_CONFIG.dm.encrypt || []).includes('messages')  // true
 
// Check if a table is derived
const isDerived = (FLOW_CONFIG.timeline.derived || []).includes('my_posts')  // true
 
// Resolve event name for a table
const eventName = FLOW_CONFIG.hello.tableMap.messages  // 'post'

import { loadFlowConfig } from '@enc-protocol/flow'
import { join } from 'node:path'
 
const flows = await loadFlowConfig(join(process.cwd(), 'config/apps'))
// { hello: { tableMap: ..., derived: ... }, dm: { ... }, ... }

interface FlowDescriptor {
  $schema: 'https://enc-protocol.dev/schemas/app-flow-v0.json'
  name: string
  description: string
  identity: { key: 'secp256k1' }
  events: Record<string, { fields: Record<string, { type: string }> }>
  encryption: Record<string, { _all: boolean, algorithm: string }>
  flows: Record<string, FlowDef>
  ingest: Record<string, IngestRule[]>
}
 
interface FlowDef {
  params: string[]
  steps: FlowStep[]
}
 
interface FlowStep {
  if?: string
  fail?: string
  return?: boolean
  submit?: { to_enclave: string, type: string, content: Record<string, string> }
  on_error?: { fail: string }
  http_get?: { url: string }
  set?: string
  then?: FlowStep[]
  merge_feed?: string
}

import { deriveFlow, deriveManifest } from '@enc-protocol/flow'
 
const v1 = deriveManifest(helloApp, enclaveRegistry)
const flow = deriveFlow(helloApp, v1, enclaveRegistry)
// {
//   $schema: 'https://enc-protocol.dev/schemas/app-flow-v0.json',
//   name: 'Hello',
//   identity: { key: 'secp256k1' },
//   events: {
//     post: { fields: { draft: { type: 'string' } } }
//   },
//   encryption: {},
//   flows: {
//     submit_post: {
//       params: ['draft'],
//       steps: [
//         { if: '!$draft', fail: 'empty draft' },
//         { submit: { to_enclave: '$myEnclave', type: 'post', content: { draft: '$draft' } } }
//       ]
//     }
//   },
//   ingest: {
//     post: [{ add_post: { id: '$ev.id', timestamp: '$ev.timestamp', draft: '$content.draft', outgoing: '$ev.from === $me' } }]
//   }
// }

interface UiDescriptor {
  $schema: 'https://enc-protocol.dev/schemas/app-ui-v0.json'
  kit_version: '0.1.0'
  name: string
  description: string
  state: Record<string, { type: string, default: string }>
  pages: Record<string, PageDef>
}
 
interface PageDef {
  header?: { title: string, subtitle?: string, back?: string | object[] }
  body: ComponentNode[]
  background?: string
}

import { deriveUi, deriveManifest } from '@enc-protocol/flow'
 
const v1 = deriveManifest(helloApp, enclaveRegistry)
const ui = deriveUi(helloApp, v1, enclaveRegistry)
// {
//   $schema: 'https://enc-protocol.dev/schemas/app-ui-v0.json',
//   kit_version: '0.1.0',
//   name: 'Hello',
//   state: {
//     page: { type: 'string', default: 'feed' },
//     draft: { type: 'string', default: '' }
//   },
//   pages: {
//     feed: {
//       header: { title: 'Feed', subtitle: '{{$runtime.messages.length}} posts' },
//       body: [
//         { type: 'list', from: '$runtime.messages', row: { type: 'PostCard', ... } },
//         { type: 'ComposeBar', draft: '$state.draft', ... }
//       ]
//     },
//     my_posts: { ... }
//   }
// }

interface EnclaveProfileV2 {
  name: string
  parties: '1' | '2' | 'N'
  readerModel: 'public' | 'member' | 'owner'
  ownerOnly: boolean            // True if no public/member readers
  events: Record<string, {
    write: string[]             // Operators that can write (non-dataview)
    read: string[]              // (always empty in current impl)
    dataviewP: boolean
  }>
  writeEventCount: number       // Events with at least one write operator
  plaintextEventCount: number   // Events with dataviewP or public reader
  encryptedEventCount: number   // writeEventCount - plaintextEventCount
  stateCount: number
  traitCount: number
}

import { profileEnclave } from '@enc-protocol/flow/engine'
 
const profile = profileEnclave('DM', dmManifest)
// {
//   name: 'DM',
//   parties: '2',
//   readerModel: 'owner',
//   ownerOnly: true,
//   events: {
//     invite: { write: ['OUTSIDER'], read: [], dataviewP: false },
//     message: { write: ['FRIEND'], read: [], dataviewP: false },
//     sent: { write: ['OWNER'], read: [], dataviewP: false },
//     rotate: { write: ['OWNER'], read: [], dataviewP: false }
//   },
//   writeEventCount: 4,
//   plaintextEventCount: 0,
//   encryptedEventCount: 4,
//   stateCount: 3,
//   traitCount: 0
// }

interface AppNeeds {
  id: string
  writes: { table: string, encrypted: boolean }[]
  readOnly: string[]                    // Tables read but never written
  needsEncryptedWrite: boolean
  needsPlaintextWrite: boolean
  encryptedCount: number
  plaintextCount: number
  totalWrites: number
}

import { analyzeApp } from '@enc-protocol/flow/engine'
 
const needs = analyzeApp(dmApp)
// {
//   id: 'dm',
//   writes: [
//     { table: 'invites', encrypted: false },
//     { table: 'messages', encrypted: true }
//   ],
//   readOnly: ['profiles'],
//   needsEncryptedWrite: true,
//   needsPlaintextWrite: true,
//   encryptedCount: 1,
//   plaintextCount: 1,
//   totalWrites: 2
// }

interface Resolution {
  appNeeds?: AppNeeds                    // Undefined if wildcard
  primary: { name: string, score: number, profile: EnclaveProfileV2 } | null
  crossEnclave: CrossEnclaveRead[]
  enclaves: string[]
  wildcard: boolean
  scores: { name: string, score: number, profile: EnclaveProfileV2 }[]  // Top 5
}

import { resolve } from '@enc-protocol/flow/engine'
 
const result = resolve(helloApp, enclaveRegistry)
// {
//   appNeeds: { id: 'hello', writes: [{ table: 'messages', encrypted: false }], ... },
//   primary: { name: 'Hello', score: 35, profile: { ... } },
//   crossEnclave: [],
//   enclaves: ['Hello'],
//   wildcard: false,
//   scores: [{ name: 'Hello', score: 35 }, ...]
// }

interface EnclaveResolution {
  primary: Map<string, { enclave: string, event: string }>  // table -> assignment
  crossEnclave: Map<string, { enclave: string, event: string }>
  enclaves: string[]
  wildcard: boolean
}

import { resolveEnclaves } from '@enc-protocol/flow/resolve-enclaves'
 
const result = resolveEnclaves(helloApp, enclaveRegistry)
// {
//   primary: Map { 'messages' => { enclave: 'Hello', event: 'post' } },
//   crossEnclave: Map {},
//   enclaves: ['Hello'],
//   wildcard: false
// }
 
const dmResult = resolveEnclaves(dmApp, enclaveRegistry)
// {
//   primary: Map {
//     'invites' => { enclave: 'DM', event: 'invite' },
//     'messages' => { enclave: 'DM', event: 'message' }
//   },
//   crossEnclave: Map { 'profiles' => { enclave: 'Registry', event: 'reg_identity' } },
//   enclaves: ['DM', 'Registry'],
//   wildcard: false
// }

export { extractSchema } from './schema.mjs'
export { deriveManifest } from './manifest.mjs'
export { match, generate, profileEnclave } from './resolver.mjs'
export { deriveFlow } from './derive-flow.mjs'
export { createSDK } from './sdk-gen.mjs'
export { FLOW_CONFIG } from './flow-config.js'

const dv = new GenericDataView(sql, helloInfra)
dv.push({
  type: 'post',
  from: '79be667ef9dcbbac',
  content: '{"body":"Hello World","from":"79be667ef9dcbbac"}',
  timestamp: 1713800000,
  id: 'evt_001',
  enclave: 'Hello',
  seq: 1,
})
// Row inserted into 'messages' table (and 'my_messages' if mapped)

const rows = dv.query('messages')
// [{ _rowid: 2, body: 'World', from: '79be...', _event_id: 'evt_002', _timestamp: 1713800001 },
//  { _rowid: 1, body: 'Hello', from: '79be...', _event_id: 'evt_001', _timestamp: 1713800000 }]
 
const recent = dv.query('messages', { limit: 10, orderBy: '_timestamp DESC' })

dv.getTables()  // ['messages']

interface Response {
  status: number
  headers: Record<string, string>   // Includes CORS headers
  body: string | null               // JSON string
}

const res = dv.handleRequest('/messages', 'GET')
// { status: 200, headers: { 'Access-Control-Allow-Origin': '*', ... },
//   body: '{"messages":[...]}' }
 
const cors = dv.handleRequest('/anything', 'OPTIONS')
// { status: 204, headers: { ... }, body: null }

import { createDataViewHandler } from './lib/generic-dataview.js'
 
const handler = createDataViewHandler(helloInfra)
// Use as CF Worker:
// export default handler

node lib/dataview-server.js <app> <port>
node lib/dataview-server.js hello 8801

interface WorkflowResult {
  commits: number                // Total commits submitted
  steps: { step: object, state: object }[]  // Per-step results
  finalState: object             // Final state after all steps
}

import { executeWorkflow } from './lib/workflow-executor.mjs'
 
const result = executeWorkflow({
  app: helloApp,
  steps: helloApp.tests[0],
  flowConfig: FLOW_CONFIG.hello,
  runAlgebraStep: (app, state, action) => runStep(app, state, { do: action }),
  submitCommit: (eventType, content) => {
    return node.processCommit(mkCommit(enclaveId, pub, eventType, content))
  },
  executeMock: (name, mock, state) => {
    return executeMockAsCommits(mock, FLOW_CONFIG.hello.tableMap, submitFn)
  },
})
// { commits: 3, steps: [...], finalState: { ... } }

// Single insert
{ op: 'insert', table: 'messages', values: { body: 'hello', from: '79be...' } }
 
// Compound operations
{ ops: [
  { op: 'insert', table: 'messages', values: { body: 'hi' } },
  { op: 'set', values: { path: '/feed' } },
] }
 
// State-only operations (produce zero commits)
{ op: 'set', values: { path: '/feed' } }
{ op: 'delete', table: 'contacts', where: { pub: 'abc' } }
{ op: 'update', table: 'users', where: { pub: 'abc' }, set: { role: 'admin' } }

import { executeMockAsCommits } from './lib/workflow-executor.mjs'
 
const count = executeMockAsCommits(
  { op: 'insert', table: 'messages', values: { body: 'hello' } },
  { messages: 'post' },
  (eventType, content) => node.processCommit(mkCommit(eid, pub, eventType, content))
)
// count: 1 (submitted 'post' event with { body: 'hello' })
 
const count2 = executeMockAsCommits(
  { ops: [
    { op: 'insert', table: 'messages', values: { body: 'msg1' } },
    { op: 'insert', table: 'messages', values: { body: 'msg2' } },
    { op: 'set', values: { path: '/feed' } },
  ] },
  { messages: 'post' },
  submitFn
)
// count2: 2 (two inserts, set is state-only)