@nbt-dev/nbt 0.0.1 → 0.0.3

package/stdlib/email/migrations/20260427235207_initial/schema_snapshot.nbt

@@ -0,0 +1,87 @@
+entity MailDomain {
+  hostname: string
+  isDefault: bool
+  domainId: string
+  sendgridParseId: string
+  sendgridDomainAuthId: string
+  verificationToken: string
+  verificationState: string
+  dkimState: string
+  spfState: string
+  createdAt: u64
+  verifiedAt: u64
+  @@unique([hostname])
+}
+
+entity Inbox {
+  name: string
+  ownerType: string
+  ownerRef: string
+  createdAt: u64
+  @@index([ownerType, ownerRef])
+}
+
+entity MailAddress {
+  mailDomainId: string
+  localPart: string
+  inboxId: string
+  enabled: bool
+  @@unique([mailDomainId, localPart])
+  @@index([mailDomainId])
+  @@index([inboxId])
+}
+
+entity Email {
+  inboxId: string
+  direction: string
+  messageId: string
+  sendgridMessageId: string
+  inReplyTo: string
+  referencesJson: string
+  fromAddr: string
+  fromName: string
+  toAddrsJson: string
+  ccAddrsJson: string
+  bccAddrsJson: string
+  subject: string
+  textBody: string
+  htmlBody: string
+  headersRaw: string
+  spamScore: string
+  receivedAt: u64
+  sentAt: u64
+  status: string
+  @@index([inboxId, receivedAt])
+  @@index([sendgridMessageId])
+  @@index([messageId])
+}
+
+entity EmailAttachment {
+  emailId: string
+  filename: string
+  contentType: string
+  sizeBytes: u64
+  contentB64: string
+  contentId: string
+  @@index([emailId])
+}
+
+entity EmailTemplate {
+  name: string
+  subjectTmpl: string
+  textTmpl: string
+  htmlTmpl: string
+  @@unique([name])
+}
+
+entity EmailEvent {
+  emailId: string
+  sendgridMessageId: string
+  type: string
+  timestamp: u64
+  reason: string
+  rawJson: string
+  @@index([emailId])
+  @@index([sendgridMessageId])
+}
+

package/stdlib/email/schema.nbt

@@ -0,0 +1,145 @@
+# Email cartridge — transactional send + synthetic inboxes.
+#
+# Provider: SendGrid (modules/sendgrid). Nothing in the user-facing surface
+# mentions SendGrid; the cart is branded "Email".
+#
+# Per-console model:
+#   - Every console auto-provisions `<console>.nbt.dev` as the default mail
+#     domain on first boot (via MailDomain.ensure_default — hit once after
+#     deploy). Users can create inboxes + addresses under it with no DNS
+#     work.
+#   - Custom domains (acme.com) go through the Domains cart: user connects
+#     Cloudflare, runs MailDomain.register → we write MX + DKIM CNAMEs,
+#     register with SendGrid Inbound Parse + Domain Authentication, poll
+#     until everything is green.
+#
+# Ops prerequisites (one-time, see plans/squishy-puzzling-spindle.md):
+#   - SENDGRID_API_KEY in console env.
+#   - SENDGRID_EVENT_PUBKEY in console env (base64 SPKI for event webhook verification).
+#   - `*.nbt.dev MX 10 mx.sendgrid.net` at zone level.
+#   - SendGrid Inbound Parse wildcard entry + per-console entries (latter are
+#     created programmatically by MailDomain.ensure_default).
+
+# Behavior (the former main.nbt actions) lives in native/runtime.jai over the
+# generated ORM — see email_register_extra_routes. These imports trigger the
+# #load of the native files into the cart module scope.
+import crypto from "crypto"
+
+# 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 SendGrid webhooks.
+@public_route "/api/email/inbound"
+@public_route "/api/email/events"
+
+entity MailDomain {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  hostname: string               # "acme.nbt.dev" or "acme.com"
+  isDefault: bool                # true for built-in <console>.nbt.dev
+  domainId: string               # FK domains cart Domain (empty for default)
+  sendgridParseId: string        # returned by sendgrid_create_inbound_parse (string id, may be hostname)
+  sendgridDomainAuthId: string   # returned by sendgrid_create_domain_auth (numeric id as string)
+  verificationToken: string      # TXT verify token (custom domains only)
+  verificationState: string      # "pending" | "verified" | "failed"
+  dkimState: string              # "pending" | "published" | "verified" | "failed"
+  spfState: string
+  verifiedAt: u64
+
+  @@unique([hostname])
+}
+
+entity Inbox {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  name: string
+  ownerType: string              # "user" | "project" | "system"
+  ownerRef: string               # id in the owning scope (empty for system)
+
+  @@index([ownerType, ownerRef])
+}
+
+entity MailAddress {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  mailDomainId: string
+  localPart: string              # "sales" or "*" for catch-all
+  inboxId: string
+  enabled: bool
+
+  @@unique([mailDomainId, localPart])
+  @@index([mailDomainId])
+  @@index([inboxId])
+}
+
+entity Email {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  inboxId: string
+  direction: string              # "inbound" | "outbound"
+  messageId: string              # RFC 5322 Message-ID (outbound: we generate; inbound: from headers)
+  sendgridMessageId: string      # SendGrid's X-Message-Id (outbound) or sg_message_id (inbound/event)
+  inReplyTo: string
+  referencesJson: string         # JSON array of Message-IDs
+  fromAddr: string
+  fromName: string
+  toAddrsJson: string            # JSON array
+  ccAddrsJson: string
+  bccAddrsJson: string
+  subject: string
+  textBody: string
+  htmlBody: string
+  headersRaw: string             # full headers blob for inbound (empty for outbound)
+  spamScore: string              # as returned by SendGrid, "" if not scored
+  receivedAt: u64
+  sentAt: u64
+  status: string                 # inbound: "received" | outbound: "queued" | "sent" | "delivered" | "bounced" | "dropped"
+
+  @@index([inboxId, receivedAt])
+  @@index([sendgridMessageId])
+  @@index([messageId])
+}
+
+entity EmailAttachment {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  emailId: string
+  filename: string
+  contentType: string
+  sizeBytes: u64
+  contentB64: string             # base64-encoded file bytes — simple for Phase 1; replace with docstore/blob ref later
+  contentId: string              # for inline images
+
+  @@index([emailId])
+}
+
+entity EmailTemplate {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  name: string
+  subjectTmpl: string
+  textTmpl: string
+  htmlTmpl: string
+
+  @@unique([name])
+}
+
+entity EmailEvent {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  emailId: string
+  sendgridMessageId: string
+  type: string                   # delivered | bounced | opened | clicked | dropped | deferred | spamreport | unsubscribe | processed
+  timestamp: u64                 # seconds since epoch (as SendGrid emits)
+  reason: string
+  rawJson: string                # entire event JSON slice for debugging
+
+  @@index([emailId])
+  @@index([sendgridMessageId])
+}

package/stdlib/ingest/README.md

@@ -0,0 +1,29 @@
+# Ingest
+
+Webhook ingestion cartridge for the console. Receives HTTP payloads from external systems, stores them as documents with automatic per-endpoint schema inference.
+
+## Entities
+
+- **Endpoint** — webhook receiver configuration (name, slug, status, secret)
+- **Payload** — received webhook data (endpointId, body as document, status, sourceIp)
+
+## Usage
+
+Create an endpoint, then POST payloads to it:
+
+```
+POST /api/ingest/endpoint/receive?e=my-webhook
+Content-Type: application/json
+
+{"customer": "alice", "amount": 99.50, "items": [{"sku": "A1", "qty": 2}]}
+```
+
+The payload body is stored in the console's docstore. Field paths, types, and frequencies are tracked automatically per endpoint — query the domain API to see the inferred schema for each endpoint's payloads.
+
+## Domain Tracking
+
+Each endpoint gets its own domain stats via `@scope(endpointId)`. Query:
+
+```
+GET /_console/docstore/<PAYLOAD_BODY_DOMAIN_BASE>/domain?scope=<endpointId>
+```

package/stdlib/ingest/migrations/20260424144652_initial/migration.nbt

@@ -0,0 +1,18 @@
+migration initial {
+  add_entity Endpoint
+  add_field Endpoint name string default("")
+  add_field Endpoint slug string default("")
+  add_field Endpoint status string default("")
+  add_field Endpoint secret string default("")
+  add_field Endpoint payloadCount u64 default(0)
+  add_field Endpoint errorCount u64 default(0)
+  add_unique Endpoint [slug]
+  add_entity Payload
+  add_field Payload endpointId string default("")
+  add_field Payload headers string default("")
+  add_field Payload body document default(0)
+  add_field Payload status string default("")
+  add_field Payload sourceIp string default("")
+  add_field Payload errorMessage string default("")
+  add_index Payload [endpointId]
+}

package/stdlib/ingest/migrations/20260424144652_initial/schema_snapshot.nbt

@@ -0,0 +1,20 @@
+entity Endpoint {
+  name: string
+  slug: string
+  status: string
+  secret: string
+  payloadCount: u64
+  errorCount: u64
+  @@unique([slug])
+}
+
+entity Payload {
+  endpointId: string
+  headers: string
+  body: document
+  status: string
+  sourceIp: string
+  errorMessage: string
+  @@index([endpointId])
+}
+

package/stdlib/ingest/migrations/20260429203747_schema_update/migration.nbt

@@ -0,0 +1,3 @@
+migration schema_update {
+  add_field Endpoint systemId string default("")
+}

package/stdlib/ingest/migrations/20260429203747_schema_update/schema_snapshot.nbt

@@ -0,0 +1,21 @@
+entity Endpoint {
+  name: string
+  slug: string
+  status: string
+  secret: string
+  payloadCount: u64
+  errorCount: u64
+  systemId?: string
+  @@unique([slug])
+}
+
+entity Payload {
+  endpointId: string
+  headers: string
+  body: document
+  status: string
+  sourceIp: string
+  errorMessage: string
+  @@index([endpointId])
+}
+

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]
+}