@nbt-dev/nbt 0.0.1 → 0.0.4

package/stdlib/ingest/schema.nbt

@@ -0,0 +1,37 @@
+# Behavior (the former main.nbt actions) lives in native/runtime.jai over the
+# generated ORM — see
+# ingest_register_extra_routes. All routes stay auth-gated by the daemon
+# middleware (no @public_route), matching the pre-migration manifest.
+
+entity Endpoint {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  name: string
+  slug: string
+  status: string
+  secret: string
+  payloadCount: u64
+  errorCount: u64
+
+  # Legacy field retained for stored rows. Previously named a downstream
+  # dispatch target; no dispatch fires today (the webhook just stores the
+  # payload and acks 200).
+  systemId?: string
+
+  @@unique([slug])
+}
+
+entity Payload {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  endpointId: string
+  headers: string
+  body: document @scope(endpointId)
+  status: string
+  sourceIp: string
+  errorMessage: string
+
+  @@index([endpointId])
+}

package/stdlib/notifications/README.md

@@ -0,0 +1,118 @@
+# Notifications cartridge
+
+Durable notification state for console-backed applications.
+
+This cartridge owns the notification record, browser push subscription state,
+and delivery bookkeeping. The portal UI accesses this cartridge through normal
+console routes. Browser-specific work such as permission prompts and service
+worker registration still happens in the portal, but the resulting subscription
+and all user-visible notification state live here.
+
+## Goals
+
+- Give every cartridge a single place to emit user notifications.
+- Keep in-app notifications, read state, and delivery attempts durable in the
+  console.
+- Support the browser Notifications API when the portal is open.
+- Support Web Push when the portal is closed by storing `PushSubscription`
+  records in the console.
+- Keep delivery channels generic enough for later email, SMS, Slack, and mobile
+  push.
+
+## Non-goals for the first pass
+
+- No direct dependency on a browser API from the console process.
+- No provider-specific Web Push implementation in the schema. VAPID signing and
+  push HTTP delivery can be implemented by a console native helper or a portal
+  worker, but both operate against this cartridge's state.
+- No cross-cartridge notification preferences yet. Preferences should be added
+  after at least two real notification sources exist.
+
+## Model
+
+`Notification` is the user-visible record. It contains title/body/url plus
+source metadata so chat, systems, agents, CRM, and other cartridges can emit
+without knowing how delivery works.
+
+`NotificationDelivery` is an outbox row. It records intended channel delivery,
+attempts, status, and provider response. For browser push, delivery rows point
+at a notification and are fulfilled using the user's active
+`BrowserPushSubscription` rows.
+
+`BrowserPushSubscription` stores the browser-provided Push API subscription for
+one signed-in user/device/browser. The portal registers the service worker,
+calls `pushManager.subscribe`, and upserts the resulting endpoint and keys here.
+
+## Initial API
+
+- `Notification.emit`
+  - Service-only action.
+  - Creates a `Notification`.
+  - Creates a pending `browser_push` delivery row by default.
+  - Later: publish a realtime event over the multiplayer hub.
+- `Notification.listMine`
+  - User action.
+  - Lists current user's notifications, optionally unread only.
+- `Notification.markRead`
+  - User action.
+  - Marks one notification read if it belongs to the current user.
+- `Notification.markAllRead`
+  - User action.
+  - Marks all current user's unread notifications read, optionally scoped to a
+    project.
+- `BrowserPushSubscription.upsertMine`
+  - User action.
+  - Stores or refreshes the current browser/device push subscription.
+- `BrowserPushSubscription.removeMine`
+  - User action.
+  - Disables one current-user subscription, usually during logout or explicit
+    notification opt-out.
+- `NotificationDelivery.recordAttempt`
+  - Service-only action.
+  - Updates delivery state after a sender attempts Web Push delivery.
+
+## Portal integration plan
+
+1. Add `public/sw.js` in the portal.
+   - Handles `push`.
+   - Calls `self.registration.showNotification`.
+   - Handles `notificationclick` by focusing or opening the notification URL.
+2. Add a small portal notification client.
+   - Registers the service worker.
+   - Requests `Notification` permission from a user gesture.
+   - Calls `registration.pushManager.subscribe`.
+   - Sends `endpoint`, `p256dh`, `auth`, `expirationTime`, and user agent to
+     `BrowserPushSubscription.upsertMine`.
+3. Replace the top-bar Bell placeholder with notification state from
+   `Notification.listMine`.
+4. Subscribe to realtime notification events when the portal is open.
+   - Use browser `new Notification(...)` only after permission is granted.
+   - Also update the Bell dropdown from the same event.
+5. Add a delivery worker.
+   - Reads pending `browser_push` deliveries.
+   - Loads active subscriptions for the notification user.
+   - Sends Web Push using VAPID.
+   - Calls `NotificationDelivery.recordAttempt`.
+   - Disables expired subscriptions after HTTP 404/410 from the push service.
+
+## Console integration plan
+
+1. Add this cartridge to the bundled core cartridge list.
+2. Generate and commit the initial migration.
+3. Add a tiny cross-cartridge helper or service route for emitting
+   notifications so other cartridges do not hand-roll HTTP calls.
+4. Update chat to emit through this cartridge after its current per-user inbox
+   fanout. Chat's existing inbox event remains useful for live unread updates;
+   notifications become the durable user-facing record.
+5. Add multiplayer fanout for `Notification.emit` so an open portal sees new
+   notifications immediately.
+
+## Delivery ownership
+
+The cartridge owns state. The delivery executor may be either:
+
+- a console native helper, preferred once VAPID/web-push support exists in Jai,
+  or
+- a portal worker that reads/writes this cartridge through service-auth routes.
+
+Both shapes keep the portal as a browser client, not the source of truth.

package/stdlib/notifications/migrations/20260430204408_initial/migration.nbt

@@ -0,0 +1,42 @@
+migration initial {
+  add_entity Notification
+  add_field Notification userId string default("")
+  add_field Notification projectId string default("")
+  add_field Notification sourceCart string default("")
+  add_field Notification sourceId string default("")
+  add_field Notification kind string default("")
+  add_field Notification title string default("")
+  add_field Notification body string default("")
+  add_field Notification url string default("")
+  add_field Notification payloadJson string default("")
+  add_field Notification readAt DateTime default(0)
+  add_field Notification archivedAt DateTime default(0)
+  add_index Notification [userId]
+  add_index Notification [projectId]
+  add_index Notification [sourceCart, sourceId]
+  add_entity NotificationDelivery
+  add_field NotificationDelivery notificationId string default("")
+  add_field NotificationDelivery userId string default("")
+  add_field NotificationDelivery channel string default("")
+  add_field NotificationDelivery status string default("")
+  add_field NotificationDelivery attempts u32 default(0)
+  add_field NotificationDelivery lastError string default("")
+  add_field NotificationDelivery providerMessageId string default("")
+  add_field NotificationDelivery lastAttemptAt DateTime default(0)
+  add_field NotificationDelivery sentAt DateTime default(0)
+  add_index NotificationDelivery [notificationId]
+  add_index NotificationDelivery [userId]
+  add_index NotificationDelivery [channel, status]
+  add_entity BrowserPushSubscription
+  add_field BrowserPushSubscription userId string default("")
+  add_field BrowserPushSubscription endpoint string default("")
+  add_field BrowserPushSubscription p256dh string default("")
+  add_field BrowserPushSubscription auth string default("")
+  add_field BrowserPushSubscription expirationTimeMs u64 default(0)
+  add_field BrowserPushSubscription userAgent string default("")
+  add_field BrowserPushSubscription deviceLabel string default("")
+  add_field BrowserPushSubscription lastSeenAt DateTime default(0)
+  add_field BrowserPushSubscription disabledAt DateTime default(0)
+  add_index BrowserPushSubscription [userId]
+  add_unique BrowserPushSubscription [endpoint]
+}

package/stdlib/notifications/migrations/20260430204408_initial/schema_snapshot.nbt

@@ -0,0 +1,46 @@
+entity Notification {
+  userId: string
+  projectId?: string
+  sourceCart?: string
+  sourceId?: string
+  kind: string
+  title: string
+  body?: string
+  url?: string
+  payloadJson?: string
+  readAt?: DateTime
+  archivedAt?: DateTime
+  @@index([userId])
+  @@index([projectId])
+  @@index([sourceCart, sourceId])
+}
+
+entity NotificationDelivery {
+  notificationId: string
+  userId: string
+  channel: string
+  status: string
+  attempts: u32
+  lastError?: string
+  providerMessageId?: string
+  lastAttemptAt?: DateTime
+  sentAt?: DateTime
+  @@index([notificationId])
+  @@index([userId])
+  @@index([channel, status])
+}
+
+entity BrowserPushSubscription {
+  userId: string
+  endpoint: string
+  p256dh: string
+  auth: string
+  expirationTimeMs?: u64
+  userAgent?: string
+  deviceLabel?: string
+  lastSeenAt: DateTime
+  disabledAt?: DateTime
+  @@unique([endpoint])
+  @@index([userId])
+}
+

package/stdlib/notifications/schema.nbt

@@ -0,0 +1,67 @@
+# Notifications cartridge — durable user notification state plus browser push
+# subscriptions. The portal owns browser permission prompts and service worker
+# registration; this cartridge owns the resulting state.
+#
+# Behavior (the former main.nbt actions) lives in native/runtime.jai as regular
+# Jai over the generated ORM — see notifications_register_extra_routes.
+
+
+entity Notification {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  userId: string
+  projectId?: string
+  sourceCart?: string
+  sourceId?: string
+  kind: string
+
+  title: string
+  body?: string
+  url?: string
+  payloadJson?: string
+
+  readAt?: DateTime
+  archivedAt?: DateTime
+
+  @@index([userId])
+  @@index([projectId])
+  @@index([sourceCart, sourceId])
+}
+
+entity NotificationDelivery {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  notificationId: string
+  userId: string
+  channel: string              # "browser_push", later "email", "sms", etc.
+  status: string               # "pending" | "sent" | "failed" | "skipped"
+  attempts: u32
+  lastError?: string
+  providerMessageId?: string
+  lastAttemptAt?: DateTime
+  sentAt?: DateTime
+
+  @@index([notificationId])
+  @@index([userId])
+  @@index([channel, status])
+}
+
+entity BrowserPushSubscription {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  userId: string
+  endpoint: string
+  p256dh: string
+  auth: string
+  expirationTimeMs?: u64
+  userAgent?: string
+  deviceLabel?: string
+  lastSeenAt: DateTime @default(now())
+  disabledAt?: DateTime
+
+  @@unique([endpoint])
+  @@index([userId])
+}

package/stdlib/phone/migrations/20260605205722_initial/migration.nbt

@@ -0,0 +1,50 @@
+migration initial {
+  add_entity TwilioAccount
+  add_field TwilioAccount name string default("")
+  add_field TwilioAccount subAccountSid string default("")
+  add_field TwilioAccount authToken string default("")
+  add_field TwilioAccount publicUrlBase string default("")
+  add_field TwilioAccount status string default("")
+  add_field TwilioAccount retentionDays s32 default(0)
+  add_index TwilioAccount [subAccountSid]
+  add_unique TwilioAccount [name]
+  add_entity PhoneNumber
+  add_field PhoneNumber accountId string default("")
+  add_field PhoneNumber phoneNumber string default("")
+  add_field PhoneNumber numberSid string default("")
+  add_field PhoneNumber friendlyName string default("")
+  add_field PhoneNumber capabilities string default("")
+  add_index PhoneNumber [accountId]
+  add_index PhoneNumber [numberSid]
+  add_unique PhoneNumber [phoneNumber]
+  add_entity SmsMessage
+  add_field SmsMessage accountId string default("")
+  add_field SmsMessage numberId string default("")
+  add_field SmsMessage direction string default("")
+  add_field SmsMessage fromE164 string default("")
+  add_field SmsMessage toE164 string default("")
+  add_field SmsMessage body string default("")
+  add_field SmsMessage twilioSid string default("")
+  add_field SmsMessage status string default("")
+  add_field SmsMessage errorCode s32 default(0)
+  add_field SmsMessage errorMessage string default("")
+  add_field SmsMessage priceMicros s64 default(0)
+  add_field SmsMessage priceCurrency string default("")
+  add_field SmsMessage numSegments s32 default(0)
+  add_field SmsMessage numMedia s32 default(0)
+  add_field SmsMessage mediaUrls string default("")
+  add_field SmsMessage senderUserId string default("")
+  add_field SmsMessage dateSentMs u64 default(0)
+  add_field SmsMessage dateDeliveredMs u64 default(0)
+  add_index SmsMessage [accountId]
+  add_index SmsMessage [numberId]
+  add_index SmsMessage [twilioSid]
+  add_entity PhoneUsageDaily
+  add_field PhoneUsageDaily accountId string default("")
+  add_field PhoneUsageDaily date string default("")
+  add_field PhoneUsageDaily smsCount s64 default(0)
+  add_field PhoneUsageDaily smsSegmentsTotal s64 default(0)
+  add_field PhoneUsageDaily smsPriceMicros s64 default(0)
+  add_index PhoneUsageDaily [accountId]
+  add_unique PhoneUsageDaily [accountId, date]
+}

package/stdlib/phone/migrations/20260605205722_initial/schema_snapshot.nbt

@@ -0,0 +1,56 @@
+entity TwilioAccount {
+  name: string
+  subAccountSid: string
+  authToken: string
+  publicUrlBase: string
+  status: string
+  retentionDays: s32
+  @@unique([name])
+  @@index([subAccountSid])
+}
+
+entity PhoneNumber {
+  accountId: string
+  phoneNumber: string
+  numberSid: string
+  friendlyName: string
+  capabilities: string
+  @@index([accountId])
+  @@unique([phoneNumber])
+  @@index([numberSid])
+}
+
+entity SmsMessage {
+  accountId: string
+  numberId: string
+  direction: string
+  fromE164: string
+  toE164: string
+  body: string
+  twilioSid: string
+  status: string
+  errorCode: s32
+  errorMessage: string
+  priceMicros: s64
+  priceCurrency: string
+  numSegments: s32
+  numMedia: s32
+  mediaUrls: string
+  senderUserId: string
+  dateSentMs: u64
+  dateDeliveredMs: u64
+  @@index([accountId])
+  @@index([numberId])
+  @@index([twilioSid])
+}
+
+entity PhoneUsageDaily {
+  accountId: string
+  date: string
+  smsCount: s64
+  smsSegmentsTotal: s64
+  smsPriceMicros: s64
+  @@unique([accountId, date])
+  @@index([accountId])
+}
+

package/stdlib/phone/schema.nbt

@@ -0,0 +1,95 @@
+# Phone cartridge — Twilio number management, SMS, click-to-call.
+#
+# Per-tenant model (see modules/twilio/module.jai for the rationale):
+#   - One master Twilio account owned by the platform (SID + auth token in
+#     env: TWILIO_MASTER_SID, TWILIO_MASTER_TOKEN).
+#   - Each tenant gets a TwilioAccount row with its own subaccount SID and
+#     auth token. All per-tenant API calls authenticate as the subaccount.
+#   - Webhooks are configured to URLs under the tenant's public base
+#     (TwilioAccount.publicUrlBase), which the gateway routes back to this
+#     cart. Signature verification uses the subaccount's auth token.
+
+# Behavior (the former jai{} helper blocks + actions) lives in
+# native/runtime.jai over the generated ORM — see phone_register_extra_routes,
+# which registers the HTTP routes.
+
+# Auth policy for the hand-written routes (formerly @public actions). The
+# handlers live in native/runtime.jai; these keep the daemon's public-route
+# manifest correct so the /api/* auth gate is bypassed for Twilio webhooks.
+@public_route "/api/phone/webhook/sms"
+@public_route "/api/phone/webhook/status"
+
+entity TwilioAccount {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  name: string               # operator-facing label
+  subAccountSid: string      # AC... — populated by provision()
+  authToken: string          # subaccount auth token (TODO: encrypt at rest)
+  publicUrlBase: string      # e.g. "https://acme.console.app"
+  status: string             # PENDING | ACTIVE | SUSPENDED | CLOSED
+  retentionDays: s32         # 0 = keep message bodies forever; N = null body after N days
+
+  @@unique([name])
+  @@index([subAccountSid])
+}
+
+entity PhoneNumber {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  accountId: string          # FK TwilioAccount.id
+  phoneNumber: string        # E.164 "+15551234567"
+  numberSid: string          # PN...
+  friendlyName: string
+  capabilities: string       # "sms"
+
+  @@index([accountId])
+  @@unique([phoneNumber])
+  @@index([numberSid])
+}
+
+entity SmsMessage {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  accountId: string
+  numberId: string           # FK PhoneNumber.id (empty on inbound if not matched)
+  direction: string          # inbound | outbound
+  fromE164: string
+  toE164: string
+  body: string               # nulled after retentionDays if TwilioAccount configured
+  twilioSid: string          # SM...
+  status: string             # queued | sent | delivered | failed | received
+  errorCode: s32
+  errorMessage: string       # human-readable sibling of errorCode
+  priceMicros: s64           # negative = charged (Twilio convention); 0 until status callback
+  priceCurrency: string      # "USD" / "CAD"
+  numSegments: s32
+  numMedia: s32
+  mediaUrls: string          # JSON array of MMS media URLs
+  senderUserId: string       # who triggered the send (empty for inbound)
+  dateSentMs: u64            # Twilio canonical timestamp (ms since epoch)
+  dateDeliveredMs: u64
+
+  @@index([accountId])
+  @@index([numberId])
+  @@index([twilioSid])
+}
+
+# Per-tenant per-day usage rollup. Written by the nightly rollup workflow;
+# read by the portal to generate invoices.
+entity PhoneUsageDaily {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  accountId: string
+  date: string                # "YYYY-MM-DD" in UTC
+  smsCount: s64
+  smsSegmentsTotal: s64
+  smsPriceMicros: s64
+
+  @@unique([accountId, date])
+  @@index([accountId])
+}
+

package/stdlib/registry/migrations/20260602181932_initial/migration.nbt

@@ -0,0 +1,8 @@
+migration initial {
+  add_entity InstalledCartridge
+  add_field InstalledCartridge tier string default("")
+  add_field InstalledCartridge source string default("")
+  add_field InstalledCartridge schemaChecksum string default("")
+  add_field InstalledCartridge installedAt u64 default(0)
+  add_field InstalledCartridge status string default("")
+}

package/stdlib/registry/migrations/20260602181932_initial/schema_snapshot.nbt

@@ -0,0 +1,8 @@
+entity InstalledCartridge {
+  tier: string
+  source: string
+  schemaChecksum: string
+  installedAt: u64
+  status: string
+}
+

package/stdlib/registry/schema.nbt

@@ -0,0 +1,20 @@
+# Installed-cartridge registry — the single source of truth for which tier-2
+# (bundled) and customer cartridges are installed on this instance.
+#
+# Lives in replicated storage, so the install set is HA-safe and survives
+# restarts: on boot the console re-activates every InstalledCartridge row.
+#
+# The console daemon is the SINGLE WRITER (cartridge_registry.jai writes rows
+# through THIS cart's generated serializer — same code, no format drift). The
+# generated CRUD routes are read-mostly, for the portal/client. The row id is
+# the cartridge name.
+entity InstalledCartridge {
+  id: string @id   # the cartridge name (slug), NOT a ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  tier: string            # "bundled" | "customer"
+  source: string          # "bundled" | "customer"
+  schemaChecksum: string  # checksum of the installed schema (drift detection)
+  installedAt: u64        # ms epoch
+  status: string          # "installed" | "failed"
+}

package/stdlib/workflows/schema.nbt

@@ -0,0 +1,44 @@
+
+# Question: How do we tie in cartridge metadata and workflow side effects into all this?
+
+enum WorkerStatus {
+  WAITING
+  RUNNING
+  TERMINATED
+}
+
+entity Worker {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  source: blob
+  contentHash: string
+  queue?: string
+  # TODO: We need some sort of termination options like a restart policy
+}
+
+# Stub — flesh out execution lifecycle fields later.
+entity WorkflowExecution {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  status: string
+  events: WorkflowExecutionEvent[]
+}
+
+# Do we want this to be a string? 
+enum WorkflowExecutionEventKind {
+  WORKFLOW_EXECUTION_STARTED
+  WORKFLOW_STEP_SCHEDULED
+  WORKFLOW_STEP_STARTED
+  WORKFLOW_STEP_COMPLETED
+  WORKFLOW_EXECUTION_COMPLETED
+}
+
+entity WorkflowExecutionEvent {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  execution: WorkflowExecution @relation(onDelete: Cascade)   # events are owned by their execution
+  kind: WorkflowExecutionEventKind
+}

package/vendor/linux-x64/cartridges/auth/migrations/20260424144652_initial/migration.nbt

@@ -0,0 +1,48 @@
+migration initial {
+  add_entity User
+  add_field User name string default("")
+  add_field User username string default("")
+  add_field User email string default("")
+  add_field User emailVerified bool default(false)
+  add_field User externalId string default("")
+  add_field User capsVersion u32 default(0)
+  add_index User [email]
+  add_index User [externalId]
+  add_entity UserRole
+  add_field UserRole userId string default("")
+  add_field UserRole cart string default("")
+  add_field UserRole role string default("")
+  add_index UserRole [userId]
+  add_entity Session
+  add_field Session userId string default("")
+  add_field Session token string default("")
+  add_field Session expiresAt DateTime default(0)
+  add_field Session ipAddress string default("")
+  add_field Session userAgent string default("")
+  add_index Session [token]
+  add_index Session [userId]
+  add_entity Account
+  add_field Account userId string default("")
+  add_field Account providerId string default("")
+  add_field Account password string default("")
+  add_field Account accessToken string default("")
+  add_field Account refreshToken string default("")
+  add_field Account idToken string default("")
+  add_field Account accessTokenExpiresAt DateTime default(0)
+  add_field Account refreshTokenExpiresAt DateTime default(0)
+  add_field Account scope string default("")
+  add_index Account [userId]
+  add_entity Verification
+  add_field Verification identifier string default("")
+  add_field Verification value string default("")
+  add_field Verification expiresAt DateTime default(0)
+  add_index Verification [identifier]
+  add_entity ApiKey
+  add_field ApiKey name string default("")
+  add_field ApiKey projectId string default("")
+  add_field ApiKey start string default("")
+  add_field ApiKey prefix string default("")
+  add_field ApiKey key string default("")
+  add_field ApiKey permissions string default("")
+  add_field ApiKey roles string default("")
+}