@stacksjs/hq 0.0.0-stage → 0.75.542

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# @stacksjs/hq
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What every Stacks HQ service does the same way: counting usage against a plan
+allowance, the connect and usage endpoints, and the typed readers an app uses to
+call a service.
+
+The services stay separate. BugHQ, LogHQ, AnalyticsHQ, StatusHQ and CommsHQ each
+keep their own accounts, keys, plans and billing; there is no central account
+and no shared login. This package shares code, never identity.
+
+It has no runtime dependencies. A database client or a store is always passed
+in, so the same code runs in a service, in a test and in an app.
+
+| Entrypoint | For |
+|---|---|
+| `@stacksjs/hq/meter` | a service counting usage and deciding what to accept |
+| `@stacksjs/hq/service` | a service mounting the connect and usage endpoints |
+| `@stacksjs/hq/client` | an app reading a service with its read key |
+| `@stacksjs/hq/testing` | the contract suite and an in-memory service |
+
+## Meter
+
+### Counter (ingest)
+
+```ts
+import { createCounter, formatUsageHeader, sqlCounterStore, USAGE_HEADER } from '@stacksjs/hq/meter'
+
+const counter = createCounter({ store: sqlCounterStore(db, { dialect: 'postgres' }) })
+
+route.post('/errors', async (request) => {
+  const admission = counter.admit(project.owner_id, 'errors', limits.errors)
+  if (admission.accept)
+    await store(event)
+  // Always 2xx. A refusal would only make the SDK retry.
+  return new Response(null, {
+    status: 202,
+    headers: { [USAGE_HEADER]: formatUsageHeader({ ...admission, upgradeUrl }) },
+  })
+})
+```
+
+`record` and `admit` touch memory and return; they never await and never query.
+A timer folds the buffered deltas into `usage_counters` every ten seconds with an
+additive upsert, so any number of instances converge on one total. A crash loses
+at most one interval of counts.
+
+The table is keyed by `(owner, meter, period)`, the period being `YYYY-MM` in
+UTC. Put `usageCountersMigrationSql({ dialect })` in a migration, or call
+`ensureUsageCountersTable(db)`. Nothing is created implicitly.
+
+`admit` counts a kept event under `meter` and a dropped one under
+`droppedMeter(meter)` (`errors.dropped`), so the reported usage is what was
+stored while the one-in-ten sequence still advances on every event received.
+
+### Reservation (sends)
+
+`reserveUsage(store, meter, quantity)` and `releaseUsage(store, reservation)`
+are a compare-and-set over a `UsageQuotaStore` you implement with `read` and
+`compareAndSet`. They never overbook under concurrency and fail closed with
+`UsageQuotaError`. To give a send its grace, store `graceCeiling(limit,
+HARD_SEND)` as the snapshot's limit.
+
+### Policy
+
+`evaluate(used, limit, policy)` is pure. `used` includes the unit being decided.
+
+| Policy | Up to the limit | Limit to 120% | Past 120% |
+|---|---|---|---|
+| `SOFT_INGEST` | `ok`, then `warn` from 80% | `over`, accepted | `sampled`, one in ten accepted |
+| `HARD_SEND` | `ok`, then `warn` from 80% | `over`, accepted | `over`, refused |
+
+`enforceQuota(meter, used, limit)` throws `QuotaExceededError` (code
+`quota_exceeded`, with `meter`, `used`, `limit`, `upgradeUrl`) when a send is
+refused. A `null` limit is unlimited.
+
+### The usage header
+
+```text
+X-HQ-Usage: errors;412;500;warn;upgrade=https%3A%2F%2Fbughq.example%2Fpricing
+```
+
+`meter;used;limit;state;upgrade=<url>`. The limit is `unlimited` for an
+unlimited meter and the URL is percent-encoded. `parseUsageHeader` answers
+`null` for anything malformed.
+
+## Service
+
+```ts
+// routes/hq.ts
+import { createHqService, sqlConnectCodeStore } from '@stacksjs/hq/service'
+
+const hq = createHqService({
+  service: 'bughq',
+  approveUrl: code => `https://bughq.example/cli/connect?code=${code}`,
+  upgradeUrl: 'https://bughq.example/pricing',
+  codes: sqlConnectCodeStore(db, { dialect: 'postgres' }),
+  provision: (user, { app }) => createOrReuseProject(user, app),
+  authenticateReadKey: key => principalForReadKey(key),
+  usage: principal => [{ meter: 'errors', used: usedBy(principal.owner), limit: limitFor(principal.owner) }],
+})
+
+for (const { method, path, handler } of hq.routes)
+  route[method.toLowerCase()](path, handler).skipCsrf()
+```
+
+| Route | Answer |
+|---|---|
+| `POST /api/cli/connect` | `201 { code, approveUrl }` |
+| `GET /api/cli/connect/{code}` | `200 { status: 'pending' }`; once approved `200 { status: 'approved', project, ingestKey, readKey, dashboardUrl }`, exactly once; otherwise `404 { status: 'expired' }` |
+| `GET /api/v1/usage` | `200 { meter, used, limit, period, state, upgradeUrl }[]`; `401` without a valid `Authorization: Bearer <read key>` |
+
+The approve page is the service's own. It calls `hq.describeConnect(code)` to
+show which app is asking and `hq.approveConnect(code, user)` when the signed-in
+user confirms.
+
+Codes are single-use and live ten minutes (`codeTtlMs`). A store only ever sees
+the SHA-256 of a code, and approved keys wait encrypted under a key derived from
+the code itself, so a copy of the table yields neither a code that can be polled
+nor a key. `connectCodesMigrationSql()` is the table for `sqlConnectCodeStore`.
+
+The handlers do not rate-limit. Put a limit on `POST /api/cli/connect` in the
+router.
+
+### Contract suite
+
+```ts
+import { hqServiceContract } from '@stacksjs/hq/testing'
+
+hqServiceContract('bughq', async () => ({ adapter, user: await signedInUser() }))
+```
+
+It covers code issue, hashing at rest, pending, approval, single use under
+concurrent polls, expiry, project reuse, read-key refusal (including the ingest
+key) and the usage shape. `createMemoryHqAdapter()` passes it and doubles as a
+stand-in service for an app's tests.
+
+## Client
+
+```ts
+import { createHqClient } from '@stacksjs/hq/client'
+
+const hq = createHqClient({
+  services: {
+    bughq: { url: env.BUGHQ_URL, readKey: env.BUGHQ_READ_KEY, project: env.BUGHQ_PROJECT },
+    loghq: { url: env.LOGHQ_URL, readKey: env.LOGHQ_READ_KEY, project: env.LOGHQ_PROJECT },
+  },
+})
+
+const usage = await hq.getUsage('bughq')
+if (usage.ok)
+  usage.data // UsageReport[]
+else
+  usage.reason // 'not_configured' | 'unauthorized' | 'timeout' | 'network' | 'http' | 'bad_response'
+```
+
+A reader never throws into the caller. A service that is down, slow (three
+seconds by default) or not configured costs the page one panel.
+
+### Readers and the endpoints behind them
+
+| Reader | Status | Endpoint |
+|---|---|---|
+| `getUsage(service)` | implemented | `GET /api/v1/usage`, mounted from `@stacksjs/hq/service` |
+| `logs.list(query)` | implemented | LogHQ `GET /api/projects/{project}/logs` with `level`, `channel`, `environment`, `trace`, `request`, `q`, `before`, `limit`; answers `{ logs, nextCursor }` |
+| `issues.list(query)` | implemented | BugHQ `GET /api/projects/{project}/issues` with `status`; answers `{ issues }` |
+| `AnalyticsReader.summary(query)` | interface only | AnalyticsHQ has no read-key endpoint. It needs `GET /api/v1/sites/{site}/summary?from&to` answering `{ pageviews, visitors, topPages: { path, pageviews }[] }` |
+| `UptimeReader.monitors()` | interface only | StatusHQ has no read-key endpoint. It needs `GET /api/v1/monitors` answering `{ monitors: { id, name, url, status, uptimePercent, lastCheckedAt }[] }` |
+| `CommsReader.summary()` | interface only | CommsHQ has no read-key endpoint. It needs `GET /api/v1/summary` answering `{ sent, delivered, bounced, contacts }` for the current period |
+
+Both implemented project readers accept the read key as a bearer token and
+answer `404` (not `401`) for a key that does not open the project, which the
+client reports as `reason: 'http'` with `status: 404`.

package/dist/client.d.ts

@@ -0,0 +1,135 @@
+import type { UsageReport, UsageState } from './types';
+export type { UsageReport, UsageState } from './types';
+export type { UsageHeader } from './usage-header';
+export declare function createHqClient(options: HqClientOptions): HqClient;
+export declare interface HqServiceConfig {
+  url: string
+  readKey: string
+  project?: string
+}
+export declare interface HqClientOptions {
+  services: Partial<Record<HqServiceName, HqServiceConfig | null | undefined>>
+  timeoutMs?: number
+  fetch?: (input: string, init?: RequestInit) => Promise<Response>
+}
+export declare interface HqUnavailable {
+  ok: false
+  unavailable: true
+  service: HqServiceName
+  reason: HqUnavailableReason
+  status?: number
+  message: string
+}
+/** LogHQ `GET /api/projects/{project}/logs`. */
+export declare interface LogQuery {
+  level?: string | string[]
+  channel?: string
+  environment?: string
+  trace?: string
+  request?: string
+  search?: string
+  before?: string
+  limit?: number
+}
+export declare interface LogEntry {
+  id: string
+  level: string
+  message: string
+  channel: string | null
+  environment: string | null
+  release: string | null
+  framework: string | null
+  host: string | null
+  timestamp: string
+  createdAt: string | null
+  traceId: string | null
+  requestId: string | null
+}
+export declare interface LogPage {
+  logs: LogEntry[]
+  nextCursor: string | null
+}
+export declare interface LogReader {
+  list: (query?: LogQuery) => Promise<HqResult<LogPage>>
+}
+/** BugHQ `GET /api/projects/{project}/issues`. */
+export declare interface IssueQuery {
+  status?: string
+}
+export declare interface Issue {
+  id: string
+  title: string
+  culprit: string | null
+  errorType: string | null
+  level: string | null
+  status: string
+  count: number
+  firstSeen: string | null
+  lastSeen: string | null
+}
+export declare interface IssueReader {
+  list: (query?: IssueQuery) => Promise<HqResult<Issue[]>>
+}
+/**
+ * The three readers below are contracts only. No service exposes a read-key
+ * endpoint for them yet; the package README lists what each must add.
+ */
+export declare interface AnalyticsQuery {
+  from?: string
+  to?: string
+}
+export declare interface AnalyticsSummary {
+  pageviews: number
+  visitors: number
+  topPages: { path: string, pageviews: number }[]
+}
+export declare interface AnalyticsReader {
+  summary: (query?: AnalyticsQuery) => Promise<HqResult<AnalyticsSummary>>
+}
+export declare interface UptimeMonitor {
+  id: string
+  name: string
+  url: string | null
+  status: 'up' | 'down' | 'paused' | 'unknown'
+  uptimePercent: number | null
+  lastCheckedAt: string | null
+}
+export declare interface UptimeReader {
+  monitors: () => Promise<HqResult<UptimeMonitor[]>>
+}
+export declare interface CommsSummary {
+  sent: number
+  delivered: number
+  bounced: number
+  contacts: number
+}
+export declare interface CommsReader {
+  summary: () => Promise<HqResult<CommsSummary>>
+}
+export declare interface HqClient {
+  getUsage: (service: HqServiceName) => Promise<HqResult<UsageReport[]>>
+  logs: LogReader
+  issues: IssueReader
+}
+/**
+ * Typed readers an app uses to call the HQ services it connected to, each
+ * with that service's own read key.
+ *
+ * One rule governs everything here: a reader NEVER throws into the caller.
+ * These run while an app renders its own dashboard, and a service being slow,
+ * down or misconfigured must cost that page a panel, not the page. Every
+ * failure is a typed `HqUnavailable` value.
+ */
+export type HqServiceName = 'bughq' | 'loghq' | 'analyticshq' | 'statushq' | 'commshq';
+export type HqUnavailableReason = | 'not_configured'
+  /** The read key was refused. */
+    | 'unauthorized'
+    | 'timeout'
+    | 'network'
+  /** The service answered with a status that is neither 2xx nor an auth refusal. */
+    | 'http'
+  /** A 2xx whose body was not the documented shape. */
+    | 'bad_response';
+export type HqResult<T> = { ok: true, data: T } | HqUnavailable;
+declare type Row = Record<string, unknown>;
+export { parseUsageHeader, USAGE_HEADER } from './usage-header';

package/dist/client.js

@@ -0,0 +1 @@
+import{isPeriod}from"./period";export{parseUsageHeader,USAGE_HEADER}from"./usage-header";const STATES=new Set(["ok","warn","over","sampled"]);function isRow(value){return typeof value==="object"&&value!==null&&!Array.isArray(value)}function text(value){if(value instanceof Date)return value.toISOString();return value===null||value===undefined?null:String(value)}function toUsageReport(value){if(!isRow(value)||typeof value.meter!=="string"||typeof value.used!=="number"||!Number.isFinite(value.used))return null;if(!(value.limit===null||typeof value.limit==="number"&&Number.isFinite(value.limit)))return null;if(typeof value.state!=="string"||!STATES.has(value.state)||!isPeriod(value.period)||typeof value.upgradeUrl!=="string")return null;return{meter:value.meter,used:value.used,limit:value.limit,period:value.period,state:value.state,upgradeUrl:value.upgradeUrl}}function toLogEntry(value){if(!isRow(value)||value.id==null||value.message==null)return null;return{id:String(value.id),level:text(value.level)??"info",message:String(value.message),channel:text(value.channel),environment:text(value.environment),release:text(value.release),framework:text(value.framework),host:text(value.host),timestamp:text(value.timestamp)??"",createdAt:text(value.created_at),traceId:text(value.trace_id),requestId:text(value.request_id)}}function toIssue(value){if(!isRow(value)||value.id==null)return null;return{id:String(value.id),title:text(value.title)??"",culprit:text(value.culprit),errorType:text(value.error_type),level:text(value.level),status:text(value.status)??"unresolved",count:Number(value.count??0)||0,firstSeen:text(value.first_seen),lastSeen:text(value.last_seen)}}function all(values,convert){if(!Array.isArray(values))return null;const out=[];for(const value of values){const converted=convert(value);if(converted===null)return null;out.push(converted)}return out}export function createHqClient(options){const timeoutMs=options.timeoutMs??3000;const send=options.fetch??((input,init)=>fetch(input,init));const unavailable=(service,reason,message,status)=>({ok:false,unavailable:true,service,reason,message,...status===undefined?{}:{status}});async function read(service,path,parse){try{const config=options.services[service];if(!config?.url||!config.readKey)return unavailable(service,"not_configured",`${service} has no url or read key configured`);const target=path(config);if(target===null)return unavailable(service,"not_configured",`${service} has no project configured`);const controller=new AbortController;const timer=setTimeout(()=>controller.abort(),timeoutMs);let response;try{response=await send(`${config.url.replace(/\/+$/,"")}${target}`,{method:"GET",headers:{Authorization:`Bearer ${config.readKey}`,Accept:"application/json"},signal:controller.signal})}catch(error){return controller.signal.aborted?unavailable(service,"timeout",`${service} did not answer within ${timeoutMs}ms`):unavailable(service,"network",error instanceof Error?error.message:String(error))}finally{clearTimeout(timer)}if(response.status===401||response.status===403)return unavailable(service,"unauthorized",`${service} refused the read key`,response.status);if(!response.ok)return unavailable(service,"http",`${service} answered ${response.status}`,response.status);const data=parse(await response.json().catch(()=>{return}));return data===null?unavailable(service,"bad_response",`${service} answered a body that is not the documented shape`,response.status):{ok:true,data}}catch(error){return unavailable(service,"network",error instanceof Error?error.message:String(error))}}const project=(config,rest,query)=>{if(!config.project)return null;const search=query?.toString();return`/api/projects/${encodeURIComponent(config.project)}${rest}${search?`?${search}`:""}`};return{getUsage:(service)=>read(service,()=>"/api/v1/usage",(body)=>all(body,toUsageReport)),logs:{list:(query={})=>{const params=new URLSearchParams;const level=Array.isArray(query.level)?query.level.join(","):query.level;const fields=[["level",level],["channel",query.channel],["environment",query.environment],["trace",query.trace],["request",query.request],["q",query.search],["before",query.before],["limit",query.limit]];for(const[name,value]of fields){if(value!==undefined&&value!=="")params.set(name,String(value))}return read("loghq",(config)=>project(config,"/logs",params),(body)=>{const logs=isRow(body)?all(body.logs,toLogEntry):null;return logs===null?null:{logs,nextCursor:text(body.nextCursor)}})}},issues:{list:(query={})=>{const params=new URLSearchParams;if(query.status)params.set("status",query.status);return read("bughq",(config)=>project(config,"/issues",params),(body)=>isRow(body)?all(body.issues,toIssue):null)}}}}

package/dist/connect-codes.d.ts

@@ -0,0 +1,40 @@
+import type { SqlClient, SqlDialect } from './types';
+export declare function createMemoryConnectCodeStore(): ConnectCodeStore & { records: () => ConnectCodeRecord[] };
+/** The package-owned schema for connect codes, for a migration or `ensureConnectCodesTable`. */
+export declare function connectCodesMigrationSql(options?: ConnectCodesSchemaOptions): string[];
+export declare function ensureConnectCodesTable(client: SqlClient, options?: ConnectCodesSchemaOptions): Promise<void>;
+/**
+ * A `ConnectCodeStore` over `hq_connect_codes`.
+ *
+ * `approve` and `consume` each win or lose by writing a random claim in a
+ * guarded UPDATE and reading it back. That needs neither RETURNING nor an
+ * affected-row count, so one implementation is atomic on all three dialects.
+ */
+export declare function sqlConnectCodeStore(client: SqlClient, options?: ConnectCodesSchemaOptions): ConnectCodeStore;
+export declare const CONNECT_CODES_TABLE: 'hq_connect_codes';
+/**
+ * One pending or approved connect attempt.
+ *
+ * The code itself is never stored: `codeHash` is its SHA-256, and
+ * `sealedGrant` is the keys encrypted under a key derived from the code. A
+ * copy of this table therefore yields neither a code that can be polled nor
+ * the keys an approved one is waiting to hand over.
+ */
+export declare interface ConnectCodeRecord {
+  codeHash: string
+  app: string
+  status: 'pending' | 'approved'
+  sealedGrant: string | null
+  expiresAt: number
+}
+export declare interface ConnectCodeStore {
+  create: (record: ConnectCodeRecord) => Promise<void>
+  find: (codeHash: string) => Promise<ConnectCodeRecord | null>
+  approve: (codeHash: string, sealedGrant: string) => Promise<boolean>
+  consume: (codeHash: string) => Promise<ConnectCodeRecord | null>
+  prune: (now: number) => Promise<void>
+}
+export declare interface ConnectCodesSchemaOptions {
+  table?: string
+  dialect?: SqlDialect
+}

package/dist/connect-codes.js

@@ -0,0 +1 @@
+import{placeholder,runSql,tableName}from"./sql";export function createMemoryConnectCodeStore(){const records=new Map;return{async create(record){records.set(record.codeHash,{...record})},async find(codeHash){const record=records.get(codeHash);return record?{...record}:null},async approve(codeHash,sealedGrant){const record=records.get(codeHash);if(!record||record.status!=="pending")return false;records.set(codeHash,{...record,status:"approved",sealedGrant});return true},async consume(codeHash){const record=records.get(codeHash);if(!record||record.status!=="approved")return null;records.delete(codeHash);return{...record}},async prune(now){for(const[hash,record]of records){if(record.expiresAt<now)records.delete(hash)}},records:()=>[...records.values()].map((record)=>({...record}))}}export const CONNECT_CODES_TABLE="hq_connect_codes";export function connectCodesMigrationSql(options={}){const table=tableName(options.table??CONNECT_CODES_TABLE);return[`CREATE TABLE IF NOT EXISTS ${table} (`+"code_hash CHAR(64) NOT NULL,"+"app VARCHAR(64) NOT NULL,"+"status VARCHAR(16) NOT NULL,"+"sealed_grant TEXT,"+"claim CHAR(36),"+"expires_at BIGINT NOT NULL,"+"PRIMARY KEY (code_hash)"+")"]}export async function ensureConnectCodesTable(client,options={}){for(const sql of connectCodesMigrationSql(options))await runSql(client,sql)}export function sqlConnectCodeStore(client,options={}){const table=tableName(options.table??CONNECT_CODES_TABLE);const dialect=options.dialect??"sqlite";const p=(n)=>placeholder(dialect,n);const columns="code_hash, app, status, sealed_grant, claim, expires_at";const toRecord=(row)=>({codeHash:String(row.code_hash),app:String(row.app),status:row.status==="approved"||row.status==="consumed"?"approved":"pending",sealedGrant:row.sealed_grant==null?null:String(row.sealed_grant),expiresAt:Number(row.expires_at)});async function row(codeHash){return(await runSql(client,`SELECT ${columns} FROM ${table} WHERE code_hash = ${p(1)} LIMIT 1`,[codeHash]))[0]??null}async function transition(codeHash,from,to,sealedGrant){const claim=crypto.randomUUID();if(sealedGrant===undefined){await runSql(client,`UPDATE ${table} SET status = ${p(1)}, claim = ${p(2)} WHERE code_hash = ${p(3)} AND status = ${p(4)}`,[to,claim,codeHash,from])}else{await runSql(client,`UPDATE ${table} SET status = ${p(1)}, claim = ${p(2)}, sealed_grant = ${p(3)} WHERE code_hash = ${p(4)} AND status = ${p(5)}`,[to,claim,sealedGrant,codeHash,from])}const after=await row(codeHash);return after&&after.status===to&&after.claim===claim?after:null}return{async create(record){await runSql(client,`INSERT INTO ${table} (code_hash, app, status, sealed_grant, expires_at) VALUES (${p(1)}, ${p(2)}, ${p(3)}, ${p(4)}, ${p(5)})`,[record.codeHash,record.app,record.status,record.sealedGrant,record.expiresAt])},async find(codeHash){const found=await row(codeHash);return found&&found.status!=="consumed"?toRecord(found):null},async approve(codeHash,sealedGrant){return await transition(codeHash,"pending","approved",sealedGrant)!==null},async consume(codeHash){const taken=await transition(codeHash,"approved","consumed");if(!taken)return null;await runSql(client,`DELETE FROM ${table} WHERE code_hash = ${p(1)}`,[codeHash]);return toRecord(taken)},async prune(now){await runSql(client,`DELETE FROM ${table} WHERE expires_at < ${p(1)}`,[now])}}}

package/dist/counter.d.ts

@@ -0,0 +1,53 @@
+import type { MeterPolicy, MeterPolicyName, UsageEvaluation } from './policy';
+/** The meter that counts events an ingest policy dropped. */
+export declare function droppedMeter(meter: string): string;
+export declare function createCounter(options: CounterOptions): UsageCounter;
+/** A `CounterStore` held in memory, for tests and for local development. */
+export declare function createMemoryCounterStore(): CounterStore & { totals: () => CounterDelta[] };
+/**
+ * Buffered usage counting for a hot path.
+ *
+ * The constraint that shapes this: it runs on ingest, the busiest endpoint a
+ * service has. Metering must add ZERO database round-trips there. So `record`
+ * and `admit` touch Maps and return, and a timer folds the accumulated deltas
+ * into the store every ten seconds.
+ *
+ * The fold is additive on the database's side (see `sqlCounterStore`), and
+ * its answer is the new durable total, which is how the in-memory view is
+ * refreshed. Nothing reads the table to decide an event.
+ *
+ * A lost flush (SIGKILL, a crash) costs at most one flush interval of counts,
+ * not the month, because the durable total already lives in the table.
+ */
+export declare interface CounterKey {
+  owner: string
+  meter: string
+  period: string
+}
+export declare interface CounterDelta extends CounterKey {
+  delta: number
+}
+export declare interface CounterStore {
+  add: (delta: CounterDelta) => Promise<number | null>
+  read: (key: CounterKey) => Promise<number>
+}
+export declare interface CounterOptions {
+  store: CounterStore
+  flushMs?: number
+  flushOnExit?: boolean
+  now?: () => Date
+  onError?: (error: unknown, key: CounterKey) => void
+}
+export declare interface Admission extends UsageEvaluation {
+  meter: string
+  accept: boolean
+}
+export declare interface UsageCounter {
+  record: (owner: string | number | null | undefined, meter: string, quantity?: number) => void
+  usageOf: (owner: string | number | null | undefined, meter: string) => number | null
+  admit: (owner: string | number | null | undefined, meter: string, limit: number | null, policy?: MeterPolicy | MeterPolicyName) => Admission
+  prime: (owner: string | number, meter: string) => Promise<void>
+  flush: () => Promise<void>
+  read: (owner: string | number, meter: string, period?: string) => Promise<number>
+  stop: () => void
+}

package/dist/counter.js

@@ -0,0 +1 @@
+import process from"node:process";import{periodOf}from"./period";import{evaluate,graceCeiling}from"./policy";export function droppedMeter(meter){return`${meter}.dropped`}const SEPARATOR="\x00";function ownerId(owner){if(owner===null||owner===undefined)return null;if(typeof owner==="number")return Number.isFinite(owner)?String(owner):null;return owner.length>0&&!owner.includes(SEPARATOR)?owner:null}function keyOf(key){return`${key.period}${SEPARATOR}${key.owner}${SEPARATOR}${key.meter}`}function parseKey(id){const[period,owner,meter]=id.split(SEPARATOR);return{owner,meter,period}}export function createCounter(options){const{store}=options;const now=options.now??(()=>new Date);const onError=options.onError??((error,key)=>{console.error("[hq:meter] counter store failed for",`${key.owner}/${key.meter}`,error instanceof Error?error.message:error)});const flushMs=options.flushMs??1e4;const pending=new Map;const inFlight=new Map;const known=new Map;const priming=new Map;const bump=(map,id,by)=>{const next=(map.get(id)??0)+by;if(next===0)map.delete(id);else map.set(id,next)};const current=(owner,meter)=>({owner,meter,period:periodOf(now())});function local(id){if(!known.has(id)&&!pending.has(id)&&!inFlight.has(id))return null;return(known.get(id)??0)+(inFlight.get(id)??0)+(pending.get(id)??0)}function record(owner,meter,quantity=1){const id=ownerId(owner);if(id===null||!meter||!Number.isFinite(quantity)||quantity<=0)return;bump(pending,keyOf(current(id,meter)),quantity)}function usageOf(owner,meter){const id=ownerId(owner);return id===null?null:local(keyOf(current(id,meter)))}function prime(owner,meter){const id=ownerId(owner);if(id===null)return Promise.resolve();const key=current(id,meter);const keyId=keyOf(key);if(known.has(keyId))return Promise.resolve();let running=priming.get(keyId);if(!running){running=store.read(key).then((total)=>{if(!known.has(keyId))known.set(keyId,Number.isFinite(total)?total:0)}).catch((error)=>onError(error,key)).finally(()=>priming.delete(keyId));priming.set(keyId,running)}return running}function admit(owner,meter,limit,policy){const id=ownerId(owner);if(id===null)return{...evaluate(0,null,policy),meter,accept:true};const kept=local(keyOf(current(id,meter)));if(kept===null){prime(id,meter);prime(id,droppedMeter(meter))}const dropped=local(keyOf(current(id,droppedMeter(meter))))??0;const candidate=(kept??0)+1;const ceiling=graceCeiling(limit,policy);const sequence=ceiling===null?undefined:candidate+dropped-ceiling;const evaluation=evaluate(candidate,limit,policy,sequence);record(id,evaluation.allowed?meter:droppedMeter(meter));return{...evaluation,used:evaluation.allowed?candidate:candidate-1,meter,accept:evaluation.allowed}}async function flush(){if(pending.size===0)return;const batch=[...pending.entries()];pending.clear();for(const[id,delta]of batch)bump(inFlight,id,delta);const period=periodOf(now());await Promise.all(batch.map(async([id,delta])=>{const key=parseKey(id);try{const total=await store.add({...key,delta});if(typeof total==="number"&&Number.isFinite(total))known.set(id,total);else known.set(id,(known.get(id)??0)+delta)}catch(error){onError(error,key)}finally{bump(inFlight,id,-delta)}}));for(const id of known.keys()){if(!id.startsWith(`${period}${SEPARATOR}`))known.delete(id)}}async function read(owner,meter,period){const id=ownerId(owner);if(id===null)return 0;const key={owner:id,meter,period:period??periodOf(now())};const keyId=keyOf(key);const buffered=(inFlight.get(keyId)??0)+(pending.get(keyId)??0);try{return await store.read(key)+buffered}catch(error){onError(error,key);return(known.get(keyId)??0)+buffered}}let timer;const onSignal=()=>{flush()};const signals=["SIGTERM","SIGINT"];if(flushMs>0){timer=setInterval(()=>{flush()},flushMs);if(typeof timer==="object"&&timer&&"unref"in timer)timer.unref()}const exitHooks=options.flushOnExit??flushMs>0;if(exitHooks){for(const signal of signals){try{process.on(signal,onSignal)}catch{}}}function stop(){if(timer!==undefined)clearInterval(timer);timer=undefined;if(exitHooks){for(const signal of signals){try{process.off(signal,onSignal)}catch{}}}}return{record,usageOf,admit,prime,flush,read,stop}}export function createMemoryCounterStore(){const totals=new Map;return{async add(delta){const next=(totals.get(keyOf(delta))??0)+delta.delta;totals.set(keyOf(delta),next);return next},async read(key){return totals.get(keyOf(key))??0},totals:()=>[...totals.entries()].map(([id,delta])=>({...parseKey(id),delta}))}}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './meter';
+export * from './service';

package/dist/index.js

@@ -0,0 +1 @@
+export*from"./client";export*from"./meter";export*from"./service";

package/dist/meter.d.ts

@@ -0,0 +1,7 @@
+export type { SqlClient, SqlDialect, UsageReport, UsageState } from './types';
+export * from './counter';
+export * from './period';
+export * from './policy';
+export * from './reservation';
+export * from './usage-counters';
+export * from './usage-header';

package/dist/meter.js

@@ -0,0 +1 @@
+export*from"./counter";export*from"./period";export*from"./policy";export*from"./reservation";export*from"./usage-counters";export*from"./usage-header";

package/dist/period.d.ts

@@ -0,0 +1,3 @@
+/** The metering period a moment falls in: `YYYY-MM`, in UTC. */
+export declare function periodOf(at?: Date | string): string;
+export declare function isPeriod(value: unknown): value is string;

package/dist/period.js

@@ -0,0 +1 @@
+export function periodOf(at=new Date){return(typeof at==="string"?at:at.toISOString()).slice(0,7)}export function isPeriod(value){return typeof value==="string"&&/^\d{4}-(?:0[1-9]|1[0-2])$/.test(value)}

package/dist/policy.d.ts

@@ -0,0 +1,66 @@
+import type { UsageState } from './types';
+export declare function resolvePolicy(policy: MeterPolicy | MeterPolicyName | undefined): MeterPolicy;
+/** The last count a policy takes in full: the limit plus its grace. */
+export declare function graceCeiling(limit: number | null, policy?: MeterPolicy | MeterPolicyName): number | null;
+/**
+ * Decide where `used` stands against `limit`. Pure: no clock, no randomness,
+ * no I/O, so the same inputs always give the same answer.
+ *
+ * `used` is the count INCLUDING the unit being decided, so `allowed` answers
+ * "is the unit that made it `used` taken?". To report standing usage with no
+ * unit in hand, pass the current count and read only `state`.
+ *
+ * Past the ceiling an ingest meter keeps every `keepEvery`th unit. Which one
+ * is decided by `sequence`, the number of units SEEN past the ceiling, kept
+ * or not. It defaults to `used - ceiling`, which is right when `used` counts
+ * everything received. A caller that counts only what it kept must pass the
+ * sequence itself, or the count stops advancing on the first dropped unit and
+ * every later one gets the same answer (`createCounter().admit` does this).
+ */
+export declare function evaluate(used: number, limit: number | null, policy?: MeterPolicy | MeterPolicyName, sequence?: number): UsageEvaluation;
+/**
+ * `evaluate`, throwing `QuotaExceededError` when the unit is not taken. Meant
+ * for sends; an ingest route should branch on `allowed` and still answer 2xx.
+ */
+export declare function enforceQuota(meter: string, used: number, limit: number | null, options?: { policy?: MeterPolicy | MeterPolicyName, upgradeUrl?: string | null }): UsageEvaluation;
+/**
+ * Ingest (errors, log lines, pageviews): never refuse. Take everything up to
+ * 120% of the allowance, then keep one event in ten. A refusal would be
+ * answered by an SDK retrying, which is more load for the same data.
+ */
+export declare const SOFT_INGEST: Readonly<MeterPolicy>;
+/**
+ * Sends (email, SMS): the caller is waiting on the answer and each unit costs
+ * money, so after a 20% grace the send is refused with a typed error.
+ */
+export declare const HARD_SEND: Readonly<MeterPolicy>;
+/**
+ * What a meter does as an account approaches and passes its allowance.
+ *
+ * Percentages are whole numbers and every threshold is computed in integers,
+ * so 120% of 500 is 600 on every machine rather than 599.9999 on some.
+ */
+export declare interface MeterPolicy {
+  kind: 'soft-ingest' | 'hard-send'
+  warnPercent: number
+  gracePercent: number
+  keepEvery: number
+}
+export declare interface UsageEvaluation {
+  state: UsageState
+  allowed: boolean
+  used: number
+  limit: number | null
+  ceiling: number | null
+}
+export type MeterPolicyName = MeterPolicy['kind'];
+/** A send refused because the account is past its allowance and its grace. */
+export declare class QuotaExceededError extends Error {
+  readonly code: 'quota_exceeded';
+  readonly meter: string;
+  readonly used: number;
+  readonly limit: number;
+  readonly upgradeUrl: string | null;
+  constructor(details: { meter: string, used: number, limit: number, upgradeUrl?: string | null });
+  toJSON(): { error: 'quota_exceeded', meter: string, used: number, limit: number, upgradeUrl: string | null };
+}

package/dist/policy.js

@@ -0,0 +1 @@
+export const SOFT_INGEST=Object.freeze({kind:"soft-ingest",warnPercent:80,gracePercent:20,keepEvery:10});export const HARD_SEND=Object.freeze({kind:"hard-send",warnPercent:80,gracePercent:20,keepEvery:1});export function resolvePolicy(policy){if(policy===undefined||policy==="soft-ingest")return SOFT_INGEST;if(policy==="hard-send")return HARD_SEND;return policy}function count(value){return Number.isFinite(value)&&value>0?Math.floor(value):0}function unlimited(limit){return limit===null||limit===undefined||limit===Number.POSITIVE_INFINITY}export function graceCeiling(limit,policy){if(unlimited(limit))return null;const allowance=count(limit);const{gracePercent}=resolvePolicy(policy);return allowance+Math.floor(allowance*count(gracePercent)/100)}export function evaluate(used,limit,policy,sequence){const resolved=resolvePolicy(policy);const total=count(used);if(unlimited(limit))return{state:"ok",allowed:true,used:total,limit:null,ceiling:null};const allowance=count(limit);const ceiling=graceCeiling(allowance,resolved);const base={used:total,limit:allowance,ceiling};if(total>ceiling){if(resolved.kind==="hard-send")return{...base,state:"over",allowed:false};const keepEvery=Math.max(1,count(resolved.keepEvery));const seen=sequence===undefined?total-ceiling:count(sequence);return{...base,state:"sampled",allowed:seen>0&&seen%keepEvery===0}}if(total>=allowance)return{...base,state:"over",allowed:true};if(total*100>=allowance*count(resolved.warnPercent))return{...base,state:"warn",allowed:true};return{...base,state:"ok",allowed:true}}export class QuotaExceededError extends Error{code="quota_exceeded";meter;used;limit;upgradeUrl;constructor(details){super(`Usage limit exceeded for ${details.meter}: ${details.used} of ${details.limit}`);this.name="QuotaExceededError";this.meter=details.meter;this.used=details.used;this.limit=details.limit;this.upgradeUrl=details.upgradeUrl??null}toJSON(){return{error:this.code,meter:this.meter,used:this.used,limit:this.limit,upgradeUrl:this.upgradeUrl}}}export function enforceQuota(meter,used,limit,options={}){const evaluation=evaluate(used,limit,options.policy??HARD_SEND);if(!evaluation.allowed)throw new QuotaExceededError({meter,used:evaluation.used,limit:evaluation.limit??0,upgradeUrl:options.upgradeUrl});return evaluation}

package/dist/reservation.d.ts

@@ -0,0 +1,23 @@
+export declare function reserveUsage(store: UsageQuotaStore, meter: string, quantity?: number, maxAttempts?: number): Promise<UsageReservation>;
+export declare function releaseUsage(store: UsageQuotaStore, reservation: UsageReservation, maxAttempts?: number): Promise<void>;
+export declare interface UsageQuotaSnapshot {
+  meter: string
+  used: number
+  limit: number | null
+}
+export declare interface UsageQuotaStore {
+  read: (meter: string) => Promise<UsageQuotaSnapshot | null>
+  compareAndSet: (snapshot: UsageQuotaSnapshot, nextUsed: number) => Promise<boolean>
+}
+export declare interface UsageReservation {
+  meter: string
+  quantity: number
+  previousUsed: number
+  used: number
+  limit: number | null
+}
+export type UsageQuotaErrorCode = 'unavailable' | 'invalid' | 'exceeded' | 'contention';
+export declare class UsageQuotaError extends Error {
+  public readonly code: UsageQuotaErrorCode;
+  constructor(code: UsageQuotaErrorCode, meter: string);
+}

package/dist/reservation.js

@@ -0,0 +1 @@
+export class UsageQuotaError extends Error{code;constructor(code,meter){const messages={unavailable:`Usage meter unavailable for ${meter}`,invalid:`Usage meter state is invalid for ${meter}`,exceeded:`Usage limit exceeded for ${meter}`,contention:`Usage reservation contention for ${meter}`};super(messages[code]);this.code=code;this.name="UsageQuotaError"}}function validQuantity(value){return Number.isFinite(value)&&value>0}function validSnapshot(snapshot,meter){return snapshot.meter===meter&&Number.isFinite(snapshot.used)&&snapshot.used>=0&&(snapshot.limit===null||Number.isFinite(snapshot.limit)&&snapshot.limit>=0)}function attempts(value){return Number.isInteger(value)&&value>0?value:1}export async function reserveUsage(store,meter,quantity=1,maxAttempts=5){if(!meter||!validQuantity(quantity))throw new UsageQuotaError("invalid",meter||"unknown");for(let attempt=0;attempt<attempts(maxAttempts);attempt++){const snapshot=await store.read(meter);if(!snapshot)throw new UsageQuotaError("unavailable",meter);if(!validSnapshot(snapshot,meter))throw new UsageQuotaError("invalid",meter);const nextUsed=snapshot.used+quantity;if(snapshot.limit!==null&&nextUsed>snapshot.limit)throw new UsageQuotaError("exceeded",meter);if(await store.compareAndSet(snapshot,nextUsed)){return{meter,quantity,previousUsed:snapshot.used,used:nextUsed,limit:snapshot.limit}}}throw new UsageQuotaError("contention",meter)}export async function releaseUsage(store,reservation,maxAttempts=5){if(!reservation.meter||!validQuantity(reservation.quantity))throw new UsageQuotaError("invalid",reservation.meter||"unknown");for(let attempt=0;attempt<attempts(maxAttempts);attempt++){const snapshot=await store.read(reservation.meter);if(!snapshot)throw new UsageQuotaError("unavailable",reservation.meter);if(!validSnapshot(snapshot,reservation.meter)||snapshot.used<reservation.quantity)throw new UsageQuotaError("invalid",reservation.meter);if(await store.compareAndSet(snapshot,snapshot.used-reservation.quantity))return}throw new UsageQuotaError("contention",reservation.meter)}

package/dist/service.d.ts

@@ -0,0 +1,83 @@
+import type { ConnectCodeStore } from './connect-codes';
+import type { MeterPolicy, MeterPolicyName } from './policy';
+import type { UsageReport } from './types';
+export type { UsageReport } from './types';
+/** SHA-256 of a connect code, hex. This, never the code, is what a store holds. */
+export declare function hashConnectCode(code: string): Promise<string>;
+export declare function createHqService<User = unknown>(adapter: HqServiceAdapter<User>, options?: HqServiceOptions): HqService<User>;
+export declare const CONNECT_PATH: '/api/cli/connect';
+export declare const USAGE_PATH: '/api/v1/usage';
+/**
+ * The three endpoints every HQ service answers the same way:
+ *
+ *   POST /api/cli/connect          -> { code, approveUrl }
+ *   GET  /api/cli/connect/{code}   -> pending | { project, ingestKey, readKey, dashboardUrl }
+ *   GET  /api/v1/usage  (read key) -> { meter, used, limit, period, state, upgradeUrl }[]
+ *
+ * Nothing here knows a router or a database. A service implements
+ * `HqServiceAdapter` over its own users, projects and keys, and mounts the
+ * handlers in its own `routes/hq.ts`. Accounts stay the service's: no
+ * identity crosses from one service to another.
+ */
+export declare interface ConnectGrant {
+  project: { id: string, name: string }
+  ingestKey: string
+  readKey: string
+  dashboardUrl: string
+}
+export declare interface ConnectRequest {
+  app: string
+}
+/** Who a read key speaks for. */
+export declare interface ReadPrincipal {
+  owner: string
+  project?: string
+}
+export declare interface MeterReading {
+  meter: string
+  used: number
+  limit: number | null
+  policy?: MeterPolicy | MeterPolicyName
+  period?: string
+}
+export declare interface HqServiceAdapter<User = unknown> {
+  service: string
+  approveUrl: (code: string) => string
+  upgradeUrl: string | ((principal: ReadPrincipal) => string)
+  codes: ConnectCodeStore
+  provision: (user: User, request: ConnectRequest) => Promise<ConnectGrant>
+  authenticateReadKey: (readKey: string) => Promise<ReadPrincipal | null>
+  usage: (principal: ReadPrincipal) => Promise<MeterReading[]>
+}
+export declare interface HqServiceOptions {
+  codeTtlMs?: number
+  now?: () => Date
+}
+/** The request shape the handlers read. A Fetch `Request` and bun-router's request both fit. */
+export declare interface HqRequest {
+  url: string
+  method?: string
+  headers: { get: (name: string) => string | null }
+  json?: () => Promise<unknown>
+  params?: Record<string, string | undefined>
+}
+export declare interface HqRoute {
+  method: 'GET' | 'POST'
+  path: string
+  handler: (request: HqRequest) => Promise<Response>
+}
+export declare interface HqService<User = unknown> {
+  startConnect: (request: HqRequest) => Promise<Response>
+  pollConnect: (request: HqRequest, code?: string) => Promise<Response>
+  describeConnect: (code: string) => Promise<{ app: string, expiresAt: number } | null>
+  approveConnect: (code: string, user: User) => Promise<ApproveResult>
+  usage: (request: HqRequest) => Promise<Response>
+  routes: HqRoute[]
+  handle: (request: HqRequest) => Promise<Response | null>
+}
+export type ConnectPollResponse = | { status: 'pending' }
+    | { status: 'expired' }
+    | ({ status: 'approved' } & ConnectGrant);
+export type ApproveResult = | { ok: true, project: ConnectGrant['project'] }
+    | { ok: false, reason: 'expired' | 'already_approved' }
+export * from './connect-codes';

package/dist/service.js

@@ -0,0 +1 @@
+import{isPeriod,periodOf}from"./period";import{evaluate}from"./policy";export*from"./connect-codes";export const CONNECT_PATH="/api/cli/connect";export const USAGE_PATH="/api/v1/usage";const encoder=new TextEncoder;const CODE=/^[\w-]{32,128}$/;function base64Url(bytes){let binary="";for(const byte of bytes)binary+=String.fromCharCode(byte);return btoa(binary).replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/,"")}function fromBase64Url(text){const binary=atob(text.replace(/-/g,"+").replace(/_/g,"/"));const bytes=new Uint8Array(new ArrayBuffer(binary.length));for(let i=0;i<binary.length;i++)bytes[i]=binary.charCodeAt(i);return bytes}export async function hashConnectCode(code){const digest=new Uint8Array(await crypto.subtle.digest("SHA-256",encoder.encode(`hq-connect-code:${code}`)));return[...digest].map((byte)=>byte.toString(16).padStart(2,"0")).join("")}async function grantKey(code){const material=await crypto.subtle.digest("SHA-256",encoder.encode(`hq-connect-grant:${code}`));return crypto.subtle.importKey("raw",material,"AES-GCM",false,["encrypt","decrypt"])}async function sealGrant(code,grant){const iv=crypto.getRandomValues(new Uint8Array(new ArrayBuffer(12)));const sealed=new Uint8Array(await crypto.subtle.encrypt({name:"AES-GCM",iv},await grantKey(code),encoder.encode(JSON.stringify(grant))));return`${base64Url(iv)}.${base64Url(sealed)}`}async function openGrant(code,sealed){try{const[iv,body]=sealed.split(".");if(!iv||!body)return null;const plain=await crypto.subtle.decrypt({name:"AES-GCM",iv:fromBase64Url(iv)},await grantKey(code),fromBase64Url(body));return JSON.parse(new TextDecoder().decode(plain))}catch{return null}}function json(body,status=200){return new Response(JSON.stringify(body),{status,headers:{"Content-Type":"application/json","Cache-Control":"no-store"}})}function appName(value){const name=typeof value==="string"?value.replace(/[^\w .-]/g,"").trim().slice(0,64):"";return name||"app"}function pathOf(request){try{return new URL(request.url,"http://localhost").pathname.replace(/\/+$/,"")||"/"}catch{return""}}function bearer(request){const header=request.headers.get("authorization")??"";const match=/^Bearer\s+(\S+)$/i.exec(header.trim());return match?.[1]??null}export function createHqService(adapter,options={}){const now=options.now??(()=>new Date);const ttl=options.codeTtlMs??10*60*1000;async function live(code){if(!CODE.test(code))return null;const codeHash=await hashConnectCode(code);const record=await adapter.codes.find(codeHash);return record&&record.expiresAt>now().getTime()?record:null}async function startConnect(request){let body;try{body=await request.json?.()}catch{}const code=base64Url(crypto.getRandomValues(new Uint8Array(32)));const at=now().getTime();await adapter.codes.prune(at).catch(()=>{});await adapter.codes.create({codeHash:await hashConnectCode(code),app:appName(body?.app),status:"pending",sealedGrant:null,expiresAt:at+ttl});return json({code,approveUrl:adapter.approveUrl(code)},201)}async function describeConnect(code){const record=await live(code);return record&&record.status==="pending"?{app:record.app,expiresAt:record.expiresAt}:null}async function approveConnect(code,user){const record=await live(code);if(!record)return{ok:false,reason:"expired"};if(record.status!=="pending")return{ok:false,reason:"already_approved"};const grant=await adapter.provision(user,{app:record.app});const approved=await adapter.codes.approve(record.codeHash,await sealGrant(code,grant));return approved?{ok:true,project:grant.project}:{ok:false,reason:"already_approved"}}async function pollConnect(request,given){const code=given??request.params?.code??decodeURIComponent(pathOf(request).split("/").pop()??"");const expired=()=>json({status:"expired"},404);const record=await live(code);if(!record)return expired();if(record.status==="pending")return json({status:"pending"});const taken=await adapter.codes.consume(record.codeHash);const grant=taken?.sealedGrant?await openGrant(code,taken.sealedGrant):null;if(!grant)return expired();return json({status:"approved",...grant})}async function usage(request){const key=bearer(request);const principal=key?await adapter.authenticateReadKey(key):null;if(!principal)return json({error:"unauthorized"},401);const upgradeUrl=typeof adapter.upgradeUrl==="function"?adapter.upgradeUrl(principal):adapter.upgradeUrl;const period=periodOf(now());const reports=(await adapter.usage(principal)).map((reading)=>{const evaluation=evaluate(reading.used,reading.limit,reading.policy);return{meter:reading.meter,used:evaluation.used,limit:evaluation.limit,period:isPeriod(reading.period)?reading.period:period,state:evaluation.state,upgradeUrl}});return json(reports)}const routes=[{method:"POST",path:CONNECT_PATH,handler:startConnect},{method:"GET",path:`${CONNECT_PATH}/{code}`,handler:(request)=>pollConnect(request)},{method:"GET",path:USAGE_PATH,handler:usage}];async function handle(request){const method=(request.method??"GET").toUpperCase();const path=pathOf(request);if(method==="POST"&&path===CONNECT_PATH)return startConnect(request);if(method==="GET"&&path.startsWith(`${CONNECT_PATH}/`)&&!path.slice(CONNECT_PATH.length+1).includes("/"))return pollConnect(request,decodeURIComponent(path.slice(CONNECT_PATH.length+1)));if(method==="GET"&&path===USAGE_PATH)return usage(request);return null}return{startConnect,pollConnect,describeConnect,approveConnect,usage,routes,handle}}

package/dist/sql.d.ts

@@ -0,0 +1,16 @@
+import type { SqlClient, SqlDialect } from './types';
+/** Table names are interpolated into DDL, so they are held to an identifier. */
+export declare function tableName(table: string): string;
+/** The nth bound parameter (1-based) in this dialect's spelling. */
+export declare function placeholder(dialect: SqlDialect, n: number): string;
+/**
+ * Run one statement and answer its rows.
+ *
+ * Clients disagree on what `unsafe` returns: a promise of rows, a lazy
+ * statement with `execute()`, or an object carrying `rows`. All three are
+ * accepted so an adapter never has to wrap its client to use these stores.
+ */
+export declare function runSql(client: SqlClient, sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+export declare class HqSchemaError extends Error {
+  constructor(message: string);
+}

package/dist/sql.js

@@ -0,0 +1 @@
+export class HqSchemaError extends Error{constructor(message){super(message);this.name="HqSchemaError"}}export function tableName(table){if(!/^[A-Z_]\w*$/i.test(table))throw new HqSchemaError(`Invalid table name '${table}'.`);return table}export function placeholder(dialect,n){return dialect==="postgres"?`$${n}`:"?"}export async function runSql(client,sql,params=[]){const statement=client.unsafe(sql,params);const result=statement&&typeof statement.execute==="function"?await statement.execute():await statement;if(Array.isArray(result))return result;const rows=result?.rows;return Array.isArray(rows)?rows:[]}

package/dist/testing.d.ts

@@ -0,0 +1,30 @@
+import type { ConnectGrant, HqServiceAdapter, MeterReading } from './service';
+export declare function hqServiceContract<User>(name: string, setup: () => HqContractHarness<User> | Promise<HqContractHarness<User>>): void;
+/**
+ * A complete adapter held in memory: a stand-in service for an app's own
+ * tests, and the reference the contract suite is checked against.
+ */
+export declare function createMemoryHqAdapter(options?: MemoryHqAdapterOptions): HqServiceAdapter<MemoryHqUser> & { grants: () => ConnectGrant[] };
+/**
+ * The contract every HQ service's adapter must pass, and an in-memory adapter
+ * that passes it.
+ *
+ * A service runs the suite against its real adapter:
+ *
+ *   import { hqServiceContract } from '@stacksjs/hq/testing'
+ *   hqServiceContract('bughq', async () => ({ adapter: bughqAdapter, user: await aSignedInUser() }))
+ *
+ * This module imports `bun:test`, so it is only for test files.
+ */
+export declare interface HqContractHarness<User> {
+  adapter: HqServiceAdapter<User>
+  user: User
+}
+export declare interface MemoryHqAdapterOptions {
+  service?: string
+  origin?: string
+  meters?: MeterReading[]
+}
+export declare interface MemoryHqUser {
+  id: string
+}

package/dist/testing.js

@@ -0,0 +1 @@
+import{describe,expect,test}from"bun:test";import{isPeriod}from"./period";import{createHqService,createMemoryConnectCodeStore,hashConnectCode}from"./service";const STATES=["ok","warn","over","sampled"];function request(url,init={}){return new Request(`http://hq.test${url}`,{method:init.method??"GET",headers:{...init.body===undefined?{}:{"Content-Type":"application/json"},...init.headers},body:init.body===undefined?undefined:JSON.stringify(init.body)})}export function hqServiceContract(name,setup){describe(`HQ service contract: ${name}`,()=>{async function boot(){const harness=await setup();const clock={at:Date.parse("2026-01-15T12:00:00.000Z")};const service=createHqService(harness.adapter,{now:()=>new Date(clock.at),codeTtlMs:60000});const start=async(app="contract-app")=>{const response=await service.handle(request("/api/cli/connect",{method:"POST",body:{app}}));expect(response?.status).toBe(201);return await response.json()};const poll=async(code)=>{const response=await service.handle(request(`/api/cli/connect/${code}`));return{status:response.status,body:await response.json()}};return{...harness,service,clock,start,poll}}test("starting a connect answers a code and an approve URL that carries it",async()=>{const{start,service}=await boot();const{code,approveUrl}=await start("my-app");expect(code).toMatch(/^[\w-]{32,}$/);expect(approveUrl).toContain(code);expect(()=>new URL(approveUrl)).not.toThrow();expect(await service.describeConnect(code)).toMatchObject({app:"my-app"})});test("two connects never share a code",async()=>{const{start}=await boot();expect((await start()).code).not.toBe((await start()).code)});test("the store is given the hash of the code, never the code",async()=>{const{start,adapter}=await boot();const{code}=await start();expect(await adapter.codes.find(code)).toBeNull();const record=await adapter.codes.find(await hashConnectCode(code));expect(record).toMatchObject({status:"pending",sealedGrant:null});expect(JSON.stringify(record)).not.toContain(code)});test("a code is pending until a signed-in user approves it",async()=>{const{start,poll}=await boot();const{code}=await start();expect(await poll(code)).toEqual({status:200,body:{status:"pending"}});expect(await poll(code)).toEqual({status:200,body:{status:"pending"}})});test("an approved code hands over the project and its keys, once",async()=>{const{start,poll,service,user,adapter}=await boot();const{code}=await start("my-app");const approval=await service.approveConnect(code,user);expect(approval.ok).toBe(true);const stored=await adapter.codes.find(await hashConnectCode(code));expect(stored?.status).toBe("approved");const first=await poll(code);expect(first.status).toBe(200);expect(first.body.status).toBe("approved");const grant=first.body;expect(typeof grant.project.id).toBe("string");expect(typeof grant.project.name).toBe("string");expect(grant.ingestKey.length).toBeGreaterThan(0);expect(grant.readKey.length).toBeGreaterThan(0);expect(grant.readKey).not.toBe(grant.ingestKey);expect(()=>new URL(grant.dashboardUrl)).not.toThrow();expect(stored?.sealedGrant??"").not.toContain(grant.readKey);expect(await poll(code)).toEqual({status:404,body:{status:"expired"}});expect(await service.approveConnect(code,user)).toEqual({ok:false,reason:"expired"})});test("concurrent polls of an approved code yield the keys exactly once",async()=>{const{start,poll,service,user}=await boot();const{code}=await start();await service.approveConnect(code,user);const outcomes=await Promise.all([poll(code),poll(code),poll(code)]);expect(outcomes.filter((outcome)=>outcome.body.status==="approved")).toHaveLength(1);expect(outcomes.filter((outcome)=>outcome.status===404)).toHaveLength(2)});test("a code cannot be approved twice",async()=>{const{start,service,user}=await boot();const{code}=await start();expect((await service.approveConnect(code,user)).ok).toBe(true);expect(await service.approveConnect(code,user)).toEqual({ok:false,reason:"already_approved"})});test("a code expires, approved or not",async()=>{const{start,poll,service,user,clock}=await boot();const pending=await start();const approved=await start();await service.approveConnect(approved.code,user);clock.at+=60001;expect(await poll(pending.code)).toEqual({status:404,body:{status:"expired"}});expect(await poll(approved.code)).toEqual({status:404,body:{status:"expired"}});expect(await service.approveConnect(pending.code,user)).toEqual({ok:false,reason:"expired"});expect(await service.describeConnect(pending.code)).toBeNull()});test("an unknown or malformed code is expired, not an error",async()=>{const{poll}=await boot();expect((await poll("a".repeat(43))).status).toBe(404);expect((await poll("nope")).status).toBe(404)});test("connecting the same app twice reuses its project",async()=>{const{start,poll,service,user}=await boot();const grants=[];for(let i=0;i<2;i++){const{code}=await start("same-app");await service.approveConnect(code,user);grants.push((await poll(code)).body)}expect(grants[1].project.id).toBe(grants[0].project.id)});test("usage refuses a missing, malformed or wrong read key",async()=>{const{service,start,poll,user}=await boot();const{code}=await start();await service.approveConnect(code,user);const grant=(await poll(code)).body;const attempts=[undefined,{Authorization:"Bearer"},{Authorization:`Basic ${grant.readKey}`},{Authorization:"Bearer not-a-key"},{Authorization:`Bearer ${grant.ingestKey}`}];for(const headers of attempts){const response=await service.handle(request("/api/v1/usage",{headers}));expect(response?.status).toBe(401)}});test("usage answers every meter in the documented shape",async()=>{const{service,start,poll,user}=await boot();const{code}=await start();await service.approveConnect(code,user);const grant=(await poll(code)).body;const response=await service.handle(request("/api/v1/usage",{headers:{Authorization:`Bearer ${grant.readKey}`}}));expect(response?.status).toBe(200);const reports=await response.json();expect(Array.isArray(reports)).toBe(true);expect(reports.length).toBeGreaterThan(0);for(const report of reports){expect(Object.keys(report).sort()).toEqual(["limit","meter","period","state","upgradeUrl","used"]);expect(report.meter).toMatch(/^[\w.:-]{1,64}$/);expect(Number.isInteger(report.used)&&report.used>=0).toBe(true);expect(report.limit===null||Number.isInteger(report.limit)&&report.limit>=0).toBe(true);expect(isPeriod(report.period)).toBe(true);expect(STATES).toContain(report.state);expect(()=>new URL(report.upgradeUrl)).not.toThrow()}expect(new Set(reports.map((report)=>report.meter)).size).toBe(reports.length)});test("requests outside the contract are left to the service",async()=>{const{service}=await boot();expect(await service.handle(request("/api/v1/other"))).toBeNull();expect(await service.handle(request("/api/cli/connect"))).toBeNull();expect(await service.handle(request("/api/v1/usage",{method:"POST",body:{}}))).toBeNull()})})}export function createMemoryHqAdapter(options={}){const service=options.service??"fakehq";const origin=options.origin??`https://${service}.test`;const meters=options.meters??[{meter:"events",used:0,limit:500}];const projects=new Map;return{service,approveUrl:(code)=>`${origin}/cli/connect?code=${encodeURIComponent(code)}`,upgradeUrl:`${origin}/pricing`,codes:createMemoryConnectCodeStore(),async provision(user,{app}){const key=`${user.id}/${app}`;let project=projects.get(key);if(!project){const id=crypto.randomUUID();project={owner:user.id,grant:{project:{id,name:app},ingestKey:`${service}_ingest_${crypto.randomUUID()}`,readKey:`${service}_read_${crypto.randomUUID()}`,dashboardUrl:`${origin}/projects/${id}`}};projects.set(key,project)}return project.grant},async authenticateReadKey(readKey){for(const{grant,owner}of projects.values()){if(grant.readKey===readKey)return{owner,project:grant.project.id}}return null},async usage(){return meters.map((reading)=>({...reading}))},grants:()=>[...projects.values()].map((project)=>project.grant)}}

package/dist/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "paths": {}
+  }
+}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/** One row of `GET /api/v1/usage`, and what a reader hands an app. */
+export declare interface UsageReport {
+  meter: string
+  used: number
+  limit: number | null
+  period: string
+  state: UsageState
+  upgradeUrl: string
+}
+/**
+ * The slice of a database client this package needs. `db` from
+ * `@stacksjs/database` satisfies it; so does anything else that can run a
+ * parameterised statement, which is what keeps this package free of a
+ * database dependency.
+ */
+export declare interface SqlClient {
+  unsafe: (sql: string, params?: unknown[]) => unknown
+}
+/**
+ * Where an account stands against one meter.
+ *
+ * - `ok`: under 80% of the allowance
+ * - `warn`: at or past 80%, still inside it
+ * - `over`: the allowance is used up; the grace is being spent (or, for a
+ *   send, has run out)
+ * - `sampled`: an ingest meter past its grace, keeping one event in ten
+ */
+export type UsageState = 'ok' | 'warn' | 'over' | 'sampled';
+export type SqlDialect = 'sqlite' | 'mysql' | 'postgres';

package/dist/usage-counters.d.ts

@@ -0,0 +1,27 @@
+import type { CounterStore } from './counter';
+import type { SqlClient, SqlDialect } from './types';
+/**
+ * The package-owned schema for `usage_counters`: one row per
+ * (owner, meter, period), `used` as a whole number of units.
+ *
+ * Returned for a service to put in a migration, or to hand to
+ * `ensureUsageCountersTable`. No migration file is written implicitly.
+ */
+export declare function usageCountersMigrationSql(options?: UsageCountersSchemaOptions): string[];
+/** Explicitly provision the table using the package-owned schema. */
+export declare function ensureUsageCountersTable(client: SqlClient, options?: UsageCountersSchemaOptions): Promise<void>;
+/**
+ * A `CounterStore` over `usage_counters`.
+ *
+ * `add` is an upsert whose update is `used = used + delta`, computed by the
+ * database. Any number of app instances therefore converge on one total
+ * instead of overwriting each other, and the statement's answer is the new
+ * total, so the counter never issues a separate read to learn where an
+ * account stands.
+ */
+export declare function sqlCounterStore(client: SqlClient, options?: UsageCountersSchemaOptions): CounterStore;
+export declare const USAGE_COUNTERS_TABLE: 'usage_counters';
+export declare interface UsageCountersSchemaOptions {
+  table?: string
+  dialect?: SqlDialect
+}

package/dist/usage-counters.js

@@ -0,0 +1 @@
+import{placeholder,runSql,tableName}from"./sql";export const USAGE_COUNTERS_TABLE="usage_counters";export function usageCountersMigrationSql(options={}){const table=tableName(options.table??USAGE_COUNTERS_TABLE);const dialect=options.dialect??"sqlite";const timestamp=dialect==="postgres"?"TIMESTAMPTZ":dialect==="mysql"?"TIMESTAMP":"DATETIME";return[`CREATE TABLE IF NOT EXISTS ${table} (`+"owner VARCHAR(191) NOT NULL,"+"meter VARCHAR(64) NOT NULL,"+"period CHAR(7) NOT NULL,"+"used BIGINT NOT NULL DEFAULT 0,"+`updated_at ${timestamp} DEFAULT CURRENT_TIMESTAMP,`+"PRIMARY KEY (owner, meter, period)"+")"]}export async function ensureUsageCountersTable(client,options={}){for(const sql of usageCountersMigrationSql(options))await runSql(client,sql)}export function sqlCounterStore(client,options={}){const table=tableName(options.table??USAGE_COUNTERS_TABLE);const dialect=options.dialect??"sqlite";const p=(n)=>placeholder(dialect,n);const select=`SELECT used FROM ${table} WHERE owner = ${p(1)} AND meter = ${p(2)} AND period = ${p(3)} LIMIT 1`;async function read(key){const row=(await runSql(client,select,[key.owner,key.meter,key.period]))[0];return Number(row?.used??0)}return{read,async add({owner,meter,period,delta}){const values=[owner,meter,period,delta];if(dialect==="mysql"){await runSql(client,`INSERT INTO ${table} (owner, meter, period, used, updated_at) VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP) `+"ON DUPLICATE KEY UPDATE used = used + VALUES(used), updated_at = CURRENT_TIMESTAMP",values);return read({owner,meter,period})}const row=(await runSql(client,`INSERT INTO ${table} (owner, meter, period, used, updated_at) VALUES (${p(1)}, ${p(2)}, ${p(3)}, ${p(4)}, CURRENT_TIMESTAMP) `+`ON CONFLICT (owner, meter, period) DO UPDATE SET used = ${table}.used + EXCLUDED.used, updated_at = CURRENT_TIMESTAMP `+"RETURNING used",values))[0];return row?Number(row.used??0):null}}}

package/dist/usage-header.d.ts

@@ -0,0 +1,22 @@
+import type { UsageState } from './types';
+/**
+ * `meter;used;limit;state;upgrade=<url>`
+ *
+ * The URL is percent-encoded so a `;` or `,` inside it cannot be read as a
+ * field or a second header value.
+ */
+export declare function formatUsageHeader(usage: UsageHeader): string;
+/**
+ * Read an `X-HQ-Usage` value. Answers `null` for anything malformed: the
+ * header is advice, and a reader must never fail a request over it.
+ */
+export declare function parseUsageHeader(value: string | null | undefined): UsageHeader | null;
+/** The response header an ingest endpoint answers with on every 2xx. */
+export declare const USAGE_HEADER: 'X-HQ-Usage';
+export declare interface UsageHeader {
+  meter: string
+  used: number
+  limit: number | null
+  state: UsageState
+  upgradeUrl: string | null
+}

package/dist/usage-header.js

@@ -0,0 +1 @@
+export const USAGE_HEADER="X-HQ-Usage";const STATES=new Set(["ok","warn","over","sampled"]);const METER=/^[\w.:-]{1,64}$/;function wholeNumber(value){return/^\d{1,15}$/.test(value)?Number(value):null}export function formatUsageHeader(usage){if(!METER.test(usage.meter))throw new TypeError(`Invalid meter name '${usage.meter}'.`);const used=Math.max(0,Math.floor(Number.isFinite(usage.used)?usage.used:0));const limit=usage.limit===null?"unlimited":String(Math.max(0,Math.floor(usage.limit)));const fields=[usage.meter,String(used),limit,usage.state];if(usage.upgradeUrl)fields.push(`upgrade=${encodeURIComponent(usage.upgradeUrl)}`);return fields.join(";")}export function parseUsageHeader(value){if(typeof value!=="string"||value.length===0||value.length>2048)return null;const[meter,usedText,limitText,state,...parameters]=value.trim().split(";").map((part)=>part.trim());if(!meter||!METER.test(meter)||usedText===undefined||limitText===undefined||!state||!STATES.has(state))return null;const used=wholeNumber(usedText);const limit=limitText==="unlimited"?null:wholeNumber(limitText);if(used===null||limit===null&&limitText!=="unlimited")return null;let upgradeUrl=null;for(const parameter of parameters){if(!parameter.startsWith("upgrade="))continue;try{const url=decodeURIComponent(parameter.slice("upgrade=".length));if(/^https?:\/\//i.test(url))upgradeUrl=url}catch{return null}}return{meter,used,limit,state,upgradeUrl}}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@stacksjs/hq",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.75.542",
+  "description": "What every Stacks HQ service does the same way: usage metering, the connect and usage endpoints, and typed readers.",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/hq#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/hq"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "metering",
+    "usage",
+    "quota",
+    "saas",
+    "stacks"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "bun": "./dist/*.js",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "bun": "./dist/*.js",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "better-dx": "^0.2.24"
+  },
+  "sideEffects": false
+}