@blotout/qinto-cli 0.1.20 → 0.1.22

package/templates/app/full/qinto.app.jsonc

@@ -1,129 +0,0 @@
-{
-  "$schema": "./node_modules/@blotout/qinto-sdk-app/app.schema.json",
-  // The immutable identifier of the app on the Qinto platform.
-  "slug": "__APP_SLUG__",
-  "name": "__APP_NAME__",
-  "description": "Rewrites events on their way through, records purchases, forwards them onward, and ships its own panel.",
-  // This app both rewrites events before destinations see them and receives them afterwards.
-  "flows": ["transform", "destination"],
-  // Events reach the app only when the visitor granted this consent category.
-  "consent": { "category": "marketing" },
-  // Replace these with your own hosted documents before publishing.
-  "legal": {
-    "termsUrl": "https://example.com/terms",
-    "privacyUrl": "https://example.com/privacy"
-  },
-  "server": {
-    "entry": "src/server.ts",
-    // Must match the __hooks the server entry exports.
-    "hooks": {
-      "transform": ["track"],
-      "onEvent": ["track", "identify"],
-      "onConnect": false,
-      "onLifecycle": ["installed", "configurationChanged", "uninstalled"]
-    },
-    // Time-based runs, with no visitor behind them — a nightly rollup, a vendor reconcile, a
-    // backfill kick-off. Each entry is attempted once per active install per matching window, best
-    // effort: a missed run is not caught up, so keep handlers repeatable. The minute field must be a
-    // literal, which is what holds a schedule to at most one run an hour; the rest is standard
-    // five-field cron in UTC, with day-of-week 0 = Sunday. Ids key the handlers the bundle
-    // registers under "schedules", and the publish refuses a mismatch either way.
-    "schedules": [{ "id": "daily-rollup", "cron": "0 2 * * *", "description": "Nightly per-install rollup" }]
-  },
-  // The browser bundle ships to the visitor's page alongside the tag. "entry" is optional: an app
-  // that only wants "capture" declares this block without shipping any browser code.
-  //
-  // "capture" names the query params and cookies the platform records against each visitor for
-  // this app, which only this app reads back. Each name belongs to one list. Uncomment to use it —
-  // a site manager sees the list and must accept any name a later version adds.
-  //
-  // "type" says what a value is: "attribution" for a click or campaign id, "identity" (the default)
-  // for a vendor id that names the visitor across visits. "expiresInSeconds" is optional and runs
-  // from the first sighting of that value; seeing the same value again never extends it. Omit it to
-  // keep the value for the life of the visitor profile.
-  // "capture": { "queryParams": [{ "name": "fbclid", "type": "attribution", "expiresInSeconds": 604800 }], "cookies": [{ "name": "_fbp" }] },
-  // eventResults lets the matching server install receive this browser handler's return value on
-  // the same action as action.browser. It is untrusted page input and delivery stays fail-open.
-  "browser": { "entry": "src/browser.ts", "eventResults": ["track"] },
-  "capabilities": {
-    "api": [],
-    // "pii" is what puts the visitor's email in ctx.user.properties.
-    "data": ["pii", "customProperties", "eventContext"]
-  },
-  // The platform creates this database, binds it as env.PURCHASES, and applies these immutable,
-  // ordered entries. Expand entries are additive and run before rollout. Use backfill handlers for
-  // resumable data work and contract entries for destructive SQL after old bundles are gone.
-  "resources": [
-    {
-      "type": "d1",
-      "identifier": "purchases",
-      "binding": "PURCHASES",
-      "migrations": [
-        {
-          "id": "001-create-purchases",
-          "phase": "expand",
-          "statements": [
-            "CREATE TABLE IF NOT EXISTS purchases (order_id TEXT PRIMARY KEY, value REAL NOT NULL, email_sha256 TEXT, recorded_at INTEGER NOT NULL)"
-          ]
-        },
-        {
-          "id": "002-index-purchases",
-          "phase": "expand",
-          "statements": ["CREATE INDEX IF NOT EXISTS purchases_recorded_at ON purchases (recorded_at)"]
-        }
-      ]
-    }
-  ],
-  // What a site manager fills in per install; a secret never reaches the browser.
-  "variables": [
-    {
-      "name": "ENDPOINT_URL",
-      "kind": "plain",
-      "type": "text",
-      "label": "Delivery endpoint",
-      "required": true,
-      "helpText": "The HTTPS endpoint each event is forwarded to. Until it is set the install stays inactive and sends nothing."
-    },
-    {
-      "name": "API_KEY",
-      "kind": "secret",
-      "type": "password",
-      "label": "API key",
-      "required": true,
-      "helpText": "The key this app authenticates to that endpoint with."
-    },
-    {
-      "name": "SITE_TAG",
-      "kind": "plain",
-      "type": "text",
-      "label": "Site tag",
-      "browser": true,
-      "helpText": "Sent with every event, and readable from the browser bundle."
-    },
-    {
-      "name": "LAST_SYNCED_AT",
-      "kind": "plain",
-      "type": "text",
-      "label": "Last synced",
-      "helpText": "Written by the panel's own /refresh handler; nobody fills this in by hand."
-    }
-  ],
-  // A site installs this app once per destination, so the panel switches between them.
-  "install": { "multiple": true, "labelHint": "e.g. EU endpoint" },
-  // Values you set once for the whole app with `qinto app var set` / `qinto app secret set`; every
-  // site that installs it gets the same one, and a required one blocks the publish until it is set.
-  // They are never written here: this file is snapshotted into the published version and readable.
-  "appVariables": [
-    {
-      "name": "VENDOR_APP_SECRET",
-      "kind": "secret",
-      "type": "password",
-      "label": "Vendor app secret",
-      "required": true,
-      "helpText": "Your own credential with the vendor, the same for every site. Set it with `qinto app secret set`."
-    }
-  ],
-  // The panel the platform renders in an iframe, and the command that builds it. "writesSettings"
-  // lets its server handler change this site's settings for the app; a site manager accepts it once.
-  "ui": { "dir": "ui/dist", "build": "npm run build", "writesSettings": true }
-}

package/templates/app/full/src/browser.ts

@@ -1,15 +0,0 @@
-import { defineBrowserApp } from '@blotout/qinto-sdk-app/browser'
-
-export default defineBrowserApp((app) => {
-  // The factory runs once per active install, with that install's
-  // browser-exposed plain variables in app.variables.
-  app.onEvent((event) => {
-    console.info('event on the page', event.event, app.variables.SITE_TAG)
-
-    return { observedAt: Date.now(), siteTag: app.variables.SITE_TAG }
-  })
-
-  app.onPush((message) => {
-    console.info('server push', message.from, message.topic, message.data)
-  })
-})

package/templates/app/full/src/server.ts

@@ -1,133 +0,0 @@
-import type { AppUiContext } from '@blotout/qinto-sdk-app/server'
-import { defineApp } from '@blotout/qinto-sdk-app/server'
-
-type Env = { PURCHASES: D1Database }
-
-// The purchases table comes from the migrations qinto.app.jsonc declares, applied at deploy.
-const INSERT_PURCHASE = 'INSERT OR REPLACE INTO purchases (order_id, value, email_sha256, recorded_at) VALUES (?, ?, ?, ?)'
-
-const sha256Hex = async (value: string): Promise<string> => {
-  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value.trim().toLowerCase()))
-  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
-}
-
-// The panel posts an install id; it is input, never authority. The handler resolves it against
-// ctx.installs, which the platform built from the site's own registry.
-const analytics = async (request: Request, ctx: AppUiContext<Env>): Promise<Response> => {
-  const { installId } = (await request.json()) as { installId: string }
-  const target = ctx.installs.find((entry) => entry.id === installId)
-  if (target === undefined) {
-    return Response.json({ error: 'unknown install' }, { status: 404 })
-  }
-
-  // That install's own secret, plus the app-scope secret you set once with `qinto app secret set`.
-  const token = target.secrets.API_KEY
-  const stats = await fetch(`${String(target.variables.ENDPOINT_URL)}/stats`, {
-    headers: { authorization: `Bearer ${token}`, 'x-app-secret': ctx.appSecrets.VENDOR_APP_SECRET }
-  })
-
-  return Response.json({ install: target.label, stats: await stats.json() })
-}
-
-// Writing a setting back needs `ui.writesSettings: true` in the manifest, and a viewer with write
-// access. The value is authoritative at once but reaches ctx.variables on the next 5-minute sync —
-// state your own code must read back immediately belongs in your own KV or D1.
-const refresh = async (request: Request, ctx: AppUiContext<Env>): Promise<Response> => {
-  const { installId } = (await request.json()) as { installId: string }
-  if (ctx.viewer.access !== 'write') {
-    return Response.json({ error: 'read-only viewer' }, { status: 403 })
-  }
-
-  await ctx.settings.write(installId, { LAST_SYNCED_AT: new Date().toISOString() })
-
-  return Response.json({ refreshed: true })
-}
-
-export default defineApp<Env>({
-  ui: async (request, ctx) => {
-    const path = new URL(request.url).pathname
-    if (path === '/analytics') {
-      return analytics(request, ctx)
-    }
-
-    if (path === '/refresh') {
-      return refresh(request, ctx)
-    }
-
-    return Response.json({ error: 'not found' }, { status: 404 })
-  },
-  transform: {
-    track: async (action, ctx) => {
-      // Reshape the payload with ctx.replace, discard the event with ctx.drop, or let it through.
-      if (action.payload.event === 'Blocked Event') {
-        return ctx.drop()
-      }
-
-      return ctx.replace({ ...action.payload, properties: { ...action.payload.properties, siteTag: ctx.variables.SITE_TAG } })
-    }
-  },
-  onEvent: {
-    track: async (action, ctx) => {
-      if (action.payload.event === 'Purchase') {
-        const email = ctx.user.properties.email
-        const emailHash = typeof email === 'string' ? await sha256Hex(email) : null
-        await ctx.env.PURCHASES.prepare(INSERT_PURCHASE)
-          .bind(String(action.payload.properties.orderId), Number(action.payload.properties.value), emailHash, action.receivedAt)
-          .run()
-        ctx.observability.log('purchase recorded', { orderId: String(action.payload.properties.orderId) })
-      }
-
-      // A plain `fetch` here is traced for you and appears in the site's real-time console;
-      // report a delivery that failed with ctx.observability.error so the trace marks it.
-      const response = await fetch(String(ctx.variables.ENDPOINT_URL), {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', authorization: `Bearer ${ctx.secrets.API_KEY}` },
-        body: JSON.stringify({
-          event: action.payload.event,
-          properties: action.payload.properties,
-          userId: action.userId,
-          context: action.context,
-          browser: action.browser
-        })
-      })
-      if (!response.ok) {
-        ctx.observability.error('delivery refused', undefined, { status: response.status, install: ctx.install.label })
-
-        return
-      }
-
-      ctx.observability.log('track delivered', { event: action.payload.event, install: ctx.install.label })
-    },
-    identify: async (action, ctx) => {
-      ctx.observability.log('identify received', { userId: action.userId, traits: Object.keys(action.payload.traits).length })
-    }
-  },
-  onLifecycle: {
-    installed: async (event, ctx) => {
-      ctx.observability.log('install ready', { eventId: event.eventId, install: ctx.install.label })
-    },
-    configurationChanged: async (event, ctx) => {
-      ctx.observability.log('configuration changed', {
-        eventId: event.eventId,
-        variables: event.changedVariables.length,
-        secrets: event.changedSecrets.length
-      })
-    },
-    uninstalled: async (event, ctx) => {
-      ctx.observability.log('install removed', { eventId: event.eventId, install: ctx.install.label })
-    }
-  },
-  // Keyed by the ids qinto.app.jsonc declares. Delivery is best effort — a run can be missed with no
-  // catch-up, and one whose response was lost may still have happened, so a handler must be safe to
-  // repeat. Work that must not be lost belongs in a workflow the handler starts.
-  schedules: {
-    'daily-rollup': async (event, ctx) => {
-      const counted = await ctx.env.PURCHASES.prepare('SELECT count(*) AS total FROM purchases').first<{ total: number }>()
-      ctx.observability.log('rollup complete', {
-        schedule: event.id,
-        install: ctx.install.label,
-        purchases: counted?.total ?? 0
-      })
-    }
-  }
-})

package/templates/app/full/ui/src/pages/index.astro

@@ -1,53 +0,0 @@
-<html lang='en'>
-  <head>
-    <meta charset='utf-8' />
-    <meta name='viewport' content='width=device-width, initial-scale=1' />
-    <title>__APP_NAME__</title>
-  </head>
-  <body>
-    <main>
-      <h1>__APP_NAME__</h1>
-      <p>The whole loop: pick an install, the panel calls this app's own <code>ui</code> server handler, and the handler reads that install's secret and calls out with the app's own credential.</p>
-
-      <label for='install'>Install</label>
-      <select id='install'></select>
-      <button id='load' type='button'>Load stats</button>
-      <button id='refresh' type='button'>Record a sync</button>
-
-      <pre id='out'>Pick an install.</pre>
-    </main>
-    <script>
-      // Resolved from the app's own dependency one directory up; the panel declares only its build tooling.
-      import { createAppUi } from '@blotout/qinto-sdk-app/ui'
-
-      const ui = createAppUi()
-      const context = await ui.getContext()
-      const out = document.getElementById('out')
-      const select = document.getElementById('install')
-
-      select.replaceChildren(
-        ...context.installs.map((install) => {
-          const option = document.createElement('option')
-          option.value = install.id
-          option.textContent = install.enabled ? install.label : `${install.label} (disabled)`
-          return option
-        })
-      )
-      select.value = context.appInstallId
-
-      // ui.fetch resolves the app's own handler and attaches the panel token. It returns the raw
-      // Response: parse it, and decide yourself what to do with a 429 or a 5xx.
-      const call = async (path) => {
-        const response = await ui.fetch(path, {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ installId: select.value })
-        })
-        out.textContent = `${response.status} ${JSON.stringify(await response.json(), null, 2)}`
-      }
-
-      document.getElementById('load').addEventListener('click', () => call('/analytics'))
-      document.getElementById('refresh').addEventListener('click', () => call('/refresh'))
-    </script>
-  </body>
-</html>

package/templates/app/minimal/qinto.app.jsonc

@@ -1,20 +0,0 @@
-{
-  "$schema": "./node_modules/@blotout/qinto-sdk-app/app.schema.json",
-  // The immutable identifier of the app on the Qinto platform.
-  "slug": "__APP_SLUG__",
-  "name": "__APP_NAME__",
-  // Where the app plugs into the event pipeline: "transform" and/or "destination".
-  "flows": ["destination"],
-  // Events reach the app only when the visitor granted this consent category.
-  "consent": { "category": "analytics" },
-  // Replace these with your own hosted documents before publishing.
-  "legal": {
-    "termsUrl": "https://example.com/terms",
-    "privacyUrl": "https://example.com/privacy"
-  },
-  "server": {
-    "entry": "src/server.ts",
-    // Must match the __hooks the server entry exports.
-    "hooks": { "transform": [], "onEvent": ["track"], "onConnect": false }
-  }
-}

package/templates/app/minimal/src/server.ts

@@ -1,9 +0,0 @@
-import { defineApp } from '@blotout/qinto-sdk-app/server'
-
-export default defineApp({
-  onEvent: {
-    track: async (action, ctx) => {
-      ctx.observability.log('track received', { event: action.payload.event, install: ctx.install.label })
-    }
-  }
-})

package/templates/project/gitignore

@@ -1,3 +0,0 @@
-node_modules/
-.qinto/
-ui/dist/

package/templates/project/package.json

@@ -1,13 +0,0 @@
-{
-  "name": "__APP_SLUG__",
-  "private": true,
-  "type": "module",
-  "dependencies": {
-    "@blotout/qinto-sdk-app": "__APP_SDK_SPECIFIER__",
-    "zod": "4.5.4"
-  },
-  "devDependencies": {
-    "@cloudflare/workers-types": "5.20260819.1",
-    "typescript": "7.0.2"
-  }
-}

package/templates/project/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "es2022",
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noEmit": true,
-    "skipLibCheck": true,
-    "types": ["@cloudflare/workers-types"]
-  },
-  "include": ["src", "mocks"]
-}

package/templates/ui/astro.config.mjs

@@ -1,6 +0,0 @@
-import { defineConfig } from 'astro/config'
-
-// The Qinto CLI injects BASE_PATH at publish time: the panel is served from /<appId>/<version>/.
-export default defineConfig({
-  base: process.env.BASE_PATH ?? '/'
-})

package/templates/ui/package.json

@@ -1,12 +0,0 @@
-{
-  "name": "__APP_SLUG__-ui",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "astro dev",
-    "build": "astro build"
-  },
-  "dependencies": {
-    "astro": "7.2.2"
-  }
-}

package/templates/ui/src/pages/index.astro

@@ -1,50 +0,0 @@
-<html lang='en'>
-  <head>
-    <meta charset='utf-8' />
-    <meta name='viewport' content='width=device-width, initial-scale=1' />
-    <title>App panel</title>
-  </head>
-  <body>
-    <main>
-      <h1>App panel</h1>
-      <p>This panel renders inside the Qinto platform. Outside it the bridge stays inert, so the fields below stay empty.</p>
-      <dl>
-        <dt>Site</dt>
-        <dd id='site'></dd>
-        <dt>Version</dt>
-        <dd id='version'></dd>
-      </dl>
-      <h2>Installs</h2>
-      <p>Every install the site made of this app, with the values it configured. A variable the manifest declares as a secret never reaches this panel — your server handler receives those.</p>
-      <ul id='installs'></ul>
-    </main>
-    <script>
-      // Resolved from the app's own dependency one directory up; the panel declares only its build tooling.
-      import { createAppUi } from '@blotout/qinto-sdk-app/ui'
-
-      const ui = createAppUi()
-      const context = await ui.getContext()
-
-      document.getElementById('site').textContent = context.siteOrigin
-      document.getElementById('version').textContent = context.appVersion
-
-      const line = (install) => {
-        const values = Object.entries(install.variables).map(([name, value]) => `${name}=${value}`)
-        const own = install.id === context.appInstallId ? ' — this panel' : ''
-        return `${install.label}${own}: ${values.join(', ') || 'nothing configured yet'}`
-      }
-
-      document.getElementById('installs').replaceChildren(
-        ...context.installs.map((install) => {
-          const item = document.createElement('li')
-          item.textContent = line(install)
-          return item
-        })
-      )
-
-      // ui.fetch(path) calls this app's own `ui` server handler with the panel token attached —
-      // that is where a secret, an app-scope credential, or a settings write belongs. getToken() is
-      // for calling your own endpoints instead.
-    </script>
-  </body>
-</html>