@stacksjs/ts-analytics 0.1.6

package/dist/infrastructure/cdk.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Generate CDK TypeScript code for analytics infrastructure
+ */
+export declare function generateCdkCode(props?: AnalyticsApiProps): string;
+/**
+ * Generate minimal CDK code for just the table (no API)
+ */
+export declare function generateCdkTableCode(props?: AnalyticsTableProps): string;
+/**
+ * Generate CreateTableInput for AWS SDK
+ */
+export declare function generateCreateTableInput(props?: AnalyticsTableProps): Record<string, unknown>;
+/**
+ * AWS CDK Construct for Analytics DynamoDB Table
+ *
+ * This module provides CDK constructs for deploying the analytics
+ * infrastructure to AWS.
+ *
+ * @example
+ * ```typescript
+ * import { AnalyticsTable } from 'dynamodb-tooling/analytics/infrastructure/cdk'
+ *
+ * const analytics = new AnalyticsTable(this, 'Analytics', {
+ *   tableName: 'my-analytics',
+ *   billingMode: BillingMode.PAY_PER_REQUEST,
+ * })
+ *
+ * // Access the table
+ * analytics.table.grantReadWriteData(myLambda)
+ * ```
+ *
+ * Note: This module exports construct props and a helper function
+ * to generate the CDK code since we can't import CDK directly
+ * (it's a peer dependency).
+ */
+// ============================================================================
+// CDK Props Types
+// ============================================================================
+export declare interface AnalyticsTableProps {
+  tableName?: string
+  billingMode?: 'PAY_PER_REQUEST' | 'PROVISIONED'
+  readCapacity?: number
+  writeCapacity?: number
+  pointInTimeRecovery?: boolean
+  stream?: 'KEYS_ONLY' | 'NEW_IMAGE' | 'OLD_IMAGE' | 'NEW_AND_OLD_IMAGES'
+  timeToLiveAttribute?: string
+  removalPolicy?: 'DESTROY' | 'RETAIN' | 'SNAPSHOT'
+  encryption?: 'AWS_MANAGED' | 'CUSTOMER_MANAGED' | 'DEFAULT'
+  encryptionKey?: string
+  deletionProtection?: boolean
+  tags?: Record<string, string>
+}
+export declare interface AnalyticsApiProps extends AnalyticsTableProps {
+  stageName?: string
+  corsOrigins?: string[]
+  memorySize?: number
+  timeout?: number
+  codePath?: string
+  enableAggregation?: boolean
+}

package/dist/infrastructure/cloudformation.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Generate CloudFormation template for analytics table
+ */
+export declare function generateCloudFormationTemplate(userConfig?: CloudFormationConfig): Record<string, unknown>;
+/**
+ * Generate CloudFormation template as JSON string
+ */
+export declare function generateCloudFormationJson(config?: CloudFormationConfig, pretty?: boolean): string;
+/**
+ * Generate CloudFormation template as YAML string
+ */
+export declare function generateCloudFormationYaml(config?: CloudFormationConfig): string;
+/**
+ * Generate SAM (Serverless Application Model) template
+ * Includes Lambda functions for API endpoints
+ */
+export declare function generateSamTemplate(config?: CloudFormationConfig): Record<string, unknown>;
+/**
+ * Generate SAM template as YAML string
+ */
+export declare function generateSamYaml(config?: CloudFormationConfig): string;
+/**
+ * CloudFormation Template Generator for Analytics DynamoDB Table
+ *
+ * Generates CloudFormation JSON/YAML for deploying the analytics
+ * single-table design to AWS.
+ */
+export declare interface CloudFormationConfig {
+  stackName?: string
+  tableName?: string
+  billingMode?: 'PAY_PER_REQUEST' | 'PROVISIONED'
+  provisionedCapacity?: {
+    readCapacityUnits: number
+    writeCapacityUnits: number
+  }
+  enablePitr?: boolean
+  enableStreams?: boolean
+  streamViewType?: 'KEYS_ONLY' | 'NEW_IMAGE' | 'OLD_IMAGE' | 'NEW_AND_OLD_IMAGES'
+  ttlAttributeName?: string
+  enableEncryption?: boolean
+  kmsKeyArn?: string
+  tags?: Record<string, string>
+  deletionProtection?: boolean
+}

package/dist/infrastructure/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Analytics Infrastructure Module
+ *
+ * Provides tools for deploying the analytics DynamoDB table:
+ * - CloudFormation templates (JSON/YAML)
+ * - SAM templates for serverless deployment
+ * - CDK code generation
+ * - AWS SDK CreateTable input
+ * - Migration utilities
+ * - Setup scripts
+ */
+// CDK
+export {
+  type AnalyticsApiProps,
+  type AnalyticsTableProps,
+  generateCdkCode,
+  generateCdkTableCode,
+  generateCreateTableInput,
+} from './cdk';
+// CloudFormation
+export {
+  type CloudFormationConfig,
+  generateCloudFormationJson,
+  generateCloudFormationTemplate,
+  generateCloudFormationYaml,
+  generateSamTemplate,
+  generateSamYaml,
+} from './cloudformation';
+// Setup & Migrations
+export {
+  checkTableStatus,
+  createAnalyticsTable,
+  createPitrMigration,
+  createStreamsMigration,
+  createTimeBasedGsiMigration,
+  type DynamoDBClientLike,
+  enableTtl,
+  generateAwsCliCommands,
+  type MigrationResult,
+  type MigrationStep,
+  printSetupInstructions,
+  runMigrations,
+  type SetupConfig,
+  type SetupResult,
+} from './setup';

package/dist/infrastructure/setup.d.ts

@@ -0,0 +1,133 @@
+import type { AnalyticsTableProps } from './cdk';
+/**
+ * Create the analytics table
+ *
+ * @example
+ * ```typescript
+ * import { DynamoDBClient, CreateTableCommand } from '@aws-sdk/client-dynamodb'
+ * import { createAnalyticsTable } from 'dynamodb-tooling/analytics/infrastructure'
+ *
+ * const client = new DynamoDBClient({ region: 'us-east-1' })
+ *
+ * const result = await createAnalyticsTable(client, {
+ *   tableName: 'my-analytics',
+ *   billingMode: 'PAY_PER_REQUEST',
+ * })
+ *
+ * console.log(`Created table: ${result.tableName}`)
+ * ```
+ */
+export declare function createAnalyticsTable(client: DynamoDBClientLike, config?: SetupConfig | undefined, commandFactories: {
+    CreateTableCommand: new (input: Record<string, unknown>) => unknown
+    DescribeTableCommand: new (input: { TableName: string }) => unknown
+  }): Promise<SetupResult>;
+/**
+ * Enable TTL on the analytics table
+ */
+export declare function enableTtl(client: DynamoDBClientLike, tableName: string, attributeName: string, commandFactory: {
+    UpdateTimeToLiveCommand: new (input: {
+      TableName: string
+      TimeToLiveSpecification: { AttributeName: string, Enabled: boolean }
+    }) => unknown
+  }): Promise<SetupResult>;
+/**
+ * Check if table exists and is active
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+export declare function checkTableStatus(client: DynamoDBClientLike, tableName: string, commandFactory: {
+    DescribeTableCommand: new (input: { TableName: string }) => unknown
+  }): Promise<{
+    exists: boolean
+    status?: string
+    itemCount?: number
+    sizeBytes?: number
+    gsiCount?: number
+  }>;
+/**
+ * Run analytics migrations
+ */
+export declare function runMigrations(client: DynamoDBClientLike, _tableName: string, migrations: MigrationStep[]): Promise<MigrationResult>;
+/**
+ * Migration: Add GSI for time-based queries
+ */
+export declare function createTimeBasedGsiMigration(tableName: string, commandFactory: {
+    UpdateTableCommand: new (input: Record<string, unknown>) => unknown
+  }): MigrationStep;
+/**
+ * Migration: Enable Point-in-Time Recovery
+ */
+export declare function createPitrMigration(tableName: string, commandFactory: {
+    UpdateContinuousBackupsCommand: new (input: Record<string, unknown>) => unknown
+  }): MigrationStep;
+/**
+ * Migration: Enable DynamoDB Streams
+ */
+export declare function createStreamsMigration(tableName: string, viewType: 'KEYS_ONLY' | 'NEW_IMAGE' | 'OLD_IMAGE' | 'NEW_AND_OLD_IMAGES', commandFactory: {
+    UpdateTableCommand: new (input: Record<string, unknown>) => unknown
+  }): MigrationStep;
+/**
+ * Print setup instructions for manual deployment
+ */
+export declare function printSetupInstructions(config?: SetupConfig): void;
+/**
+ * Generate AWS CLI commands for table creation
+ */
+export declare function generateAwsCliCommands(config?: SetupConfig): string;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface SetupConfig extends AnalyticsTableProps {
+  region?: string
+  endpoint?: string
+  waitForActive?: boolean
+  waitTimeout?: number
+}
+export declare interface SetupResult {
+  success: boolean
+  tableName: string
+  tableArn?: string
+  error?: string
+}
+export declare interface MigrationStep {
+  name: string
+  description: string
+  execute: (client: DynamoDBClientLike) => Promise<void>
+  rollback?: (client: DynamoDBClientLike) => Promise<void>
+}
+export declare interface MigrationResult {
+  success: boolean
+  stepsCompleted: string[]
+  error?: string
+  failedStep?: string
+}
+/**
+ * Minimal DynamoDB client interface
+ * Allows using either AWS SDK v2 or v3
+ */
+export declare interface DynamoDBClientLike {
+  send: (command: unknown) => Promise<unknown>
+}
+/**
+ * CreateTable command interface
+ */
+export declare interface CreateTableCommandLike {
+  input: Record<string, unknown>
+}
+/**
+ * DescribeTable command interface
+ */
+export declare interface DescribeTableCommandLike {
+  input: { TableName: string }
+}
+/**
+ * UpdateTimeToLive command interface
+ */
+export declare interface UpdateTimeToLiveCommandLike {
+  input: {
+    TableName: string
+    TimeToLiveSpecification: {
+      AttributeName: string
+      Enabled: boolean
+    }
+  }
+}

package/dist/integrations/cloudflare.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Create a Cloudflare Workers fetch handler for analytics
+ */
+export declare function createAnalyticsHandler(options?: CloudflareHandlerOptions): (
+  request: Request,
+  env: CloudflareEnv,
+  ctx: ExecutionContext,
+) => Promise<Response>;
+/**
+ * Create a D1 storage adapter for SQLite-based storage
+ */
+export declare function createD1Adapter(db: D1Database): StorageAdapter;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface CloudflareEnv {
+  DYNAMODB_ENDPOINT?: string
+  AWS_REGION?: string
+  AWS_ACCESS_KEY_ID?: string
+  AWS_SECRET_ACCESS_KEY?: string
+  SESSIONS_KV?: KVNamespace
+  D1_DATABASE?: D1Database
+  TABLE_NAME?: string
+}
+declare interface KVNamespace {
+  get: (key: string, options?: { type?: string }) => Promise<string | null>
+  put: (key: string, value: string, options?: { expirationTtl?: number }) => Promise<void>
+  delete: (key: string) => Promise<void>
+}
+declare interface D1Database {
+  prepare: (sql: string) => D1PreparedStatement
+  exec: (sql: string) => Promise<D1ExecResult>
+  batch: <T>(statements: D1PreparedStatement[]) => Promise<D1Result<T>[]>
+}
+declare interface D1PreparedStatement {
+  bind: (...values: unknown[]) => D1PreparedStatement
+  first: <T>() => Promise<T | null>
+  all: <T>() => Promise<D1Result<T>>
+  run: () => Promise<D1Result<unknown>>
+}
+declare interface D1Result<T> {
+  results?: T[]
+  success: boolean
+  meta?: Record<string, unknown>
+}
+declare interface D1ExecResult {
+  count: number
+  duration: number
+}
+export declare interface CloudflareHandlerOptions {
+  corsOrigins?: string[]
+  basePath?: string
+  sessionTtl?: number
+  storage?: StorageAdapter
+}
+export declare interface StorageAdapter {
+  putItem: (tableName: string, item: Record<string, unknown>) => Promise<void>
+  query: (tableName: string, params: QueryParams) => Promise<QueryResult>
+}
+declare interface QueryParams {
+  pk: string
+  skPrefix?: string
+  skStart?: string
+  skEnd?: string
+  indexName?: string
+  limit?: number
+}
+declare interface QueryResult {
+  items: Record<string, unknown>[]
+  lastKey?: string
+}
+// Cloudflare Workers types
+declare interface ExecutionContext {
+  waitUntil: (promise: Promise<unknown>) => void
+  passThroughOnException: () => void
+}

package/dist/integrations/hono.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Create analytics middleware for Hono
+ *
+ * Adds analytics context to requests and handles CORS.
+ */
+export declare function analyticsMiddleware(options?: Partial<AnalyticsMiddlewareOptions>): HonoMiddleware;
+/**
+ * Create analytics routes for Hono
+ */
+export declare function createAnalyticsRoutes(options: AnalyticsMiddlewareOptions): {
+  collect: (c: HonoContext) => Promise<Response>
+  stats: (c: HonoContext) => Promise<Response>
+  realtime: (c: HonoContext) => Promise<Response>
+  script: (c: HonoContext) => Response
+  sites: (c: HonoContext) => Promise<Response>
+  createSite: (c: HonoContext) => Promise<Response>
+};
+/**
+ * Mount analytics routes on a Hono app
+ */
+export declare function mountAnalyticsRoutes(app: HonoApp, basePath: string, options: AnalyticsMiddlewareOptions): void;
+// ============================================================================
+// Types
+// ============================================================================
+declare interface HonoContext {
+  req: {
+    url: string
+    method: string
+    header: (name: string) => string | undefined
+    param: (name: string) => string | undefined
+    query: (name: string) => string | undefined
+    json: <T>() => Promise<T>
+  }
+  json: (data: unknown, status?: number) => Response
+  text: (data: string, status?: number) => Response
+  body: (data: unknown, status?: number) => Response
+  set: (name: string, value: unknown) => void
+  get: (name: string) => unknown
+}
+declare interface HonoApp {
+  use: (path: string, ...handlers: HonoMiddleware[]) => void
+  get: (path: string, handler: (c: HonoContext) => Promise<Response> | Response) => void
+  post: (path: string, handler: (c: HonoContext) => Promise<Response> | Response) => void
+  options: (path: string, handler: (c: HonoContext) => Promise<Response> | Response) => void
+}
+export declare interface AnalyticsMiddlewareOptions {
+  skipPaths?: string[]
+  getVisitorId?: (c: HonoContext) => Promise<string>
+  sessionStore?: SessionStore
+  executeCommand: (cmd: DynamoCommand) => Promise<unknown>
+}
+declare interface SessionStore {
+  get: (key: string) => Promise<Session | null>
+  set: (key: string, session: Session, ttlSeconds?: number) => Promise<void>
+}
+declare interface DynamoCommand {
+  command: string
+  input: Record<string, unknown>
+}
+declare type HonoMiddleware = (c: HonoContext, next: () => Promise<void>) => Promise<Response | void>;

package/dist/integrations/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Framework Integrations
+ *
+ * Pre-built integrations for popular frameworks.
+ */
+export {
+  analyticsMiddleware,
+  createAnalyticsRoutes,
+  mountAnalyticsRoutes,
+  type AnalyticsMiddlewareOptions,
+} from './hono';
+export {
+  createAnalyticsHandler,
+  createD1Adapter,
+  type CloudflareEnv,
+  type CloudflareHandlerOptions,
+  type StorageAdapter,
+} from './cloudflare';
+export {
+  type StxHeadScript,
+  tsAnalytics,
+  type TsAnalyticsOptions,
+  tsAnalyticsTag,
+} from './stx';

package/dist/integrations/nuxt.d.ts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+import { type TsAnalyticsOptions } from './stx';
+declare const tsAnalyticsNuxtModule: NuxtModule<TsAnalyticsNuxtOptions>;
+export declare interface TsAnalyticsNuxtOptions extends TsAnalyticsOptions {
+  enabled?: boolean
+}
+export default tsAnalyticsNuxtModule;

package/dist/integrations/nuxt.js

@@ -0,0 +1,42 @@
+// @bun
+import {
+  resolveApiEndpoint,
+  tsAnalytics
+} from "../chunk-deephkz6.js";
+import"../chunk-2mx7fq49.js";
+
+// src/integrations/nuxt.ts
+import { addImports, createResolver, defineNuxtModule } from "@nuxt/kit";
+var tsAnalyticsNuxtModule = defineNuxtModule({
+  meta: {
+    name: "@stacksjs/ts-analytics",
+    configKey: "tsAnalytics",
+    compatibility: { nuxt: ">=3.0.0" }
+  },
+  defaults: { enabled: true },
+  setup(options, nuxt) {
+    if (options.enabled === false)
+      return;
+    const scripts = tsAnalytics(options);
+    if (scripts.length === 0) {
+      console.warn("[ts-analytics] module skipped \u2014 `appId` is required in nuxt.config `tsAnalytics`.");
+      return;
+    }
+    nuxt.options.app.head.script = nuxt.options.app.head.script || [];
+    nuxt.options.app.head.script.push(...scripts);
+    nuxt.options.runtimeConfig.public.tsAnalytics = {
+      appId: options.appId,
+      apiEndpoint: resolveApiEndpoint(options.apiEndpoint)
+    };
+    const resolver = createResolver(import.meta.url);
+    addImports({
+      name: "useTsAnalytics",
+      as: "useTsAnalytics",
+      from: resolver.resolve("./runtime/use-ts-analytics")
+    });
+  }
+});
+var nuxt_default = tsAnalyticsNuxtModule;
+export {
+  nuxt_default as default
+};

package/dist/integrations/runtime/use-ts-analytics.d.ts

@@ -0,0 +1,18 @@
+export declare function useTsAnalytics(): TsAnalyticsApi;
+/**
+ * `useTsAnalytics()` — custom event tracking for the ts-analytics Nuxt module.
+ *
+ * The injected tracker exposes a Fathom-API-compatible global
+ * (`window.fathom.track(name, value)`); this composable wraps it with an
+ * SSR-safe no-op on the server. Auto-imported by `@stacksjs/ts-analytics/nuxt`.
+ *
+ * ```ts
+ * const { track } = useTsAnalytics()
+ * track('signup')
+ * track('purchase', 4200) // optional numeric value (e.g. cents)
+ * track('signup', 0, { plan: 'pro' }) // custom properties
+ * ```
+ */
+export declare interface TsAnalyticsApi {
+  track: (name: string, value?: number, props?: Record<string, string | number | boolean>) => void
+}

package/dist/integrations/runtime/use-ts-analytics.js

@@ -0,0 +1,17 @@
+// @bun
+import"../../chunk-2mx7fq49.js";
+
+// src/integrations/runtime/use-ts-analytics.ts
+function useTsAnalytics() {
+  return {
+    track(name, value, props) {
+      if (typeof window === "undefined")
+        return;
+      const tracker = window.fathom;
+      tracker?.track?.(name, value, props);
+    }
+  };
+}
+export {
+  useTsAnalytics
+};

package/dist/integrations/stx.d.ts

@@ -0,0 +1,88 @@
+/** Resolve the API origin from an explicit override, env, then the default. */
+export declare function resolveApiEndpoint(explicit?: string): string;
+/**
+ * Build the ts-analytics head `<script>` entry for a stx/Stacks app config.
+ *
+ * Returns an **array** (so it spreads cleanly into `app.head.script` and can
+ * grow later — e.g. an error-tracking tag — without changing call sites).
+ * Returns `[]` when `appId`/`apiEndpoint` are missing, so a half-configured
+ * environment never injects a broken tag.
+ */
+export declare function tsAnalytics(options: TsAnalyticsOptions): StxHeadScript[];
+/**
+ * Raw `<script>` tag string for non-stx contexts — paste into a plain HTML
+ * `<head>`, or inject server-side. Same inputs as {@link tsAnalytics}. Returns
+ * `''` when required options are missing.
+ */
+export declare function tsAnalyticsTag(options: TsAnalyticsOptions): string;
+/**
+ * Default ts-analytics API origin — where `/script.js` is served and events are
+ * collected. Baked in (Fathom-style) so host apps supply *only* an App ID.
+ *
+ * Endpoint resolution order: an explicit `apiEndpoint` option → the
+ * `TS_ANALYTICS_ENDPOINT` env var → this constant. Set this to your production
+ * ts-analytics host so deployed apps need zero endpoint config.
+ */
+export declare const DEFAULT_API_ENDPOINT: 'http://localhost:2027';
+/** A stx head `<script>` entry — an item of the config `app.head.script` array. */
+export declare interface StxHeadScript {
+  src?: string
+  content?: string
+  defer?: boolean
+  async?: boolean
+  type?: string
+  [attr: string]: unknown
+}
+export declare interface TsAnalyticsOptions {
+  appId: string
+  apiEndpoint?: string
+  scriptPath?: string
+  stealth?: boolean
+}
+/**
+ * stx / Stacks Config Integration
+ *
+ * Add ts-analytics to a stx (or Stacks) app the way you'd add a Nuxt analytics
+ * module — from the config file, keyed by an **App ID**.
+ *
+ * ts-analytics serves one shared, cacheable tracker at `<apiEndpoint>/script.js`
+ * (Fathom/Plausible-style). The tracker reads its App ID from the `data-site`
+ * attribute and derives the collector endpoint from its own `src` origin, so
+ * the only thing a host app supplies is the App ID + the API origin.
+ *
+ * Spread the result into your stx config's `app.head.script`:
+ *
+ * ```ts
+ * // config/stx.ts (Stacks)  — or  stx.config.ts
+ * import { tsAnalytics } from '@stacksjs/ts-analytics/stx'
+ *
+ * export default {
+ *   app: {
+ *     head: {
+ *       script: [
+ *         ...tsAnalytics({ appId: 'my-app' }),   // endpoint is baked in
+ *       ],
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * **Why a head helper and not a `plugins: [...]` entry?** stx's plugin render
+ * lifecycle hooks (`afterRender`) are not invoked by the dev/serve render
+ * pipeline, and a plugin's `setup()` config mutation does not propagate to
+ * rendering. The head config *is* read on every render, so this is the reliable
+ * mechanism — and it mirrors what framework analytics modules do internally
+ * (push a tag onto the document head).
+ */
+/**
+ * Generate a short, unguessable App ID (Fathom-style `data-site`, 8 chars). Run
+ * once per site and paste the result into your config — the backend
+ * auto-provisions the site on its first event, so nothing else is needed.
+ *
+ * ```ts
+ * import { generateAppId } from '@stacksjs/ts-analytics/stx'
+ * console.log(generateAppId()) // e.g. 'K7MN4PQR'
+ * ```
+ */
+export { generateAppId } from '../lib/crypto-random';
+export default tsAnalytics;

package/dist/integrations/stx.js

@@ -0,0 +1,18 @@
+// @bun
+import {
+  DEFAULT_API_ENDPOINT,
+  generateAppId,
+  resolveApiEndpoint,
+  stx_default,
+  tsAnalytics,
+  tsAnalyticsTag
+} from "../chunk-deephkz6.js";
+import"../chunk-2mx7fq49.js";
+export {
+  tsAnalyticsTag,
+  tsAnalytics,
+  resolveApiEndpoint,
+  generateAppId,
+  stx_default as default,
+  DEFAULT_API_ENDPOINT
+};

package/dist/lib/crypto-random.d.ts

@@ -0,0 +1,4 @@
+/** A random string of `length` chars drawn uniformly from `chars`. */
+export declare function randomToken(length: number, chars?: string): string;
+/** A short, random, unguessable App ID (default 8 chars). */
+export declare function generateAppId(length?: number): string;

package/dist/lib/salt.d.ts

@@ -0,0 +1,16 @@
+/** Daily-rotating, secret-seeded salt for visitor ID hashing.
+ *
+ * NOTE: process-local — on multi-instance deployments prefer
+ * {@link getSharedDailySalt}, which persists the day's salt in DynamoDB so
+ * every instance hashes with the same value.
+ */
+export declare function getDailySalt(): string;
+/**
+ * Cluster-consistent daily salt (#165). The process-local salt differs per
+ * instance when ANALYTICS_SALT_SECRET is unset (Lambda concurrency, restarts),
+ * which inflates unique-visitor counts — the same visitor hashes differently on
+ * every instance. Persist the day's salt as a SALT item via conditional put
+ * (first writer wins) so all instances converge, with the process-local value
+ * as both the candidate and the fallback when DynamoDB is unreachable.
+ */
+export declare function getSharedDailySalt(): Promise<string>;