@alfredmouelle/create-stack 0.1.1 → 0.2.0

package/_stack/apps/tanstack-base/src/components/ui/spinner.tsx

@@ -2,7 +2,7 @@ import { Loader2 } from 'lucide-react'
 import type { ComponentProps } from 'react'
 import { cn } from '~/lib/utils'
 
-/** Loading indicator — the lucide `loader` icon, spinning. */
+/** Spinning lucide `loader` icon. */
 export function Spinner({ className, ...props }: ComponentProps<typeof Loader2>) {
   return <Loader2 aria-hidden="true" className={cn('size-4 animate-spin', className)} {...props} />
 }

package/_stack/apps/tanstack-base/src/emails/components/components.tsx

@@ -5,9 +5,9 @@ import { createEmailTheme, type EmailTheme, type EmailThemeOverride } from './th
 export interface EmailLayoutProps {
   preview: string
   children: React.ReactNode
-  /** Per-email theme override, merged onto the default theme. */
+  /** Per-email theme override, merged onto default. */
   theme?: EmailTheme | EmailThemeOverride
-  /** Footer year. Pass explicitly to keep rendered output deterministic. */
+  /** Footer year; pass explicitly for deterministic output. */
   year?: number
 }
 

package/_stack/apps/tanstack-base/src/emails/components/context.tsx

@@ -12,7 +12,7 @@ export function EmailThemeProvider({ theme, children }: EmailThemeProviderProps)
   return <EmailThemeContext.Provider value={theme}>{children}</EmailThemeContext.Provider>
 }
 
-/** Read the active email theme. Falls back to {@link defaultTheme}. */
+/** Active email theme; falls back to {@link defaultTheme}. */
 export function useEmailTheme(): EmailTheme {
   return useContext(EmailThemeContext)
 }

package/_stack/apps/tanstack-base/src/emails/components/theme.ts

@@ -1,13 +1,12 @@
 /**
- * The swappable design tokens for emails. Override any subset via
- * {@link createEmailTheme} and pass the result to `<EmailLayout theme={...}>`,
- * or wrap a tree in `<EmailThemeProvider>`.
+ * Swappable email design tokens. Override a subset via {@link createEmailTheme}
+ * + `<EmailLayout theme={...}>`, or wrap a tree in `<EmailThemeProvider>`.
  */
 export interface EmailTheme {
   brand: {
-    /** Shown in the header band and footer. */
+    /** Header band + footer. */
     name: string
-    /** Footer line (the year is prefixed automatically). */
+    /** Footer line (year prefixed automatically). */
     footer: string
   }
   fontFamily: string
@@ -21,7 +20,7 @@ export interface EmailTheme {
     border: string
     borderSubtle: string
     destructive: string
-    /** Text color on top of accent/destructive buttons. */
+    /** Text over accent/destructive buttons. */
     onAccent: string
   }
 }
@@ -52,7 +51,7 @@ export type EmailThemeOverride = {
   colors?: Partial<EmailTheme['colors']>
 }
 
-/** Deep-merge an override onto a base theme (defaults to {@link defaultTheme}). */
+/** Deep-merge override onto base (defaults to {@link defaultTheme}). */
 export function createEmailTheme(
   override: EmailThemeOverride = {},
   base: EmailTheme = defaultTheme,

package/_stack/apps/tanstack-base/src/env.ts

@@ -1,15 +1,11 @@
 import { createEnv } from '@t3-oss/env-core'
 import * as v from 'valibot'
 
-/** Makes a var required only in production (optional in dev/test). */
+/** Required in production, optional in dev/test. */
 export const requiredInProduction = <T extends v.GenericSchema>(schema: T) =>
   process.env.NODE_ENV === 'production' ? schema : v.optional(schema)
 
-/**
- * Typed environment. Start minimal — patterns (drizzle, better-auth, …) and
- * capabilities (add-capability) extend the `server` block and `runtimeEnv` with
- * the keys they need.
- */
+/** Typed env; foundations/capabilities extend `server` + `runtimeEnv` as needed. */
 export const env = createEnv({
   shared: {
     NODE_ENV: v.optional(v.picklist(['development', 'test', 'production']), 'development'),

package/_stack/apps/tanstack-base/src/lib/date.ts

@@ -1,4 +1,4 @@
 import { format } from 'date-fns'
 
-/** Format a Date as an ISO date string (yyyy-MM-dd). */
+/** Format as ISO date (yyyy-MM-dd). */
 export const toISODate = (date: Date): string => format(date, 'yyyy-MM-dd')

package/_stack/apps/tanstack-base/src/routes/__root.tsx

@@ -8,7 +8,7 @@ import TanStackQueryDevtools from '~/trpc/devtools'
 
 import appCss from '../styles.css?url'
 
-// Runs before hydration to set the theme class and avoid a flash of wrong theme.
+// Pre-hydration: set theme class to avoid flash of wrong theme.
 const themeScript = `(function(){try{var t=localStorage.getItem('theme')||'system';var m=window.matchMedia('(prefers-color-scheme:dark)').matches;document.documentElement.classList.toggle('dark',t==='dark'||(t==='system'&&m));}catch(e){}})();`
 
 interface RouterContext {

package/_stack/apps/tanstack-base/src/routes/_authed.tsx

@@ -1,10 +1,7 @@
 import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
 import { getServerSession } from '~/server/better-auth/session'
 
-/**
- * Layout group guarding every route under it: redirects to sign-in when there's
- * no session, and exposes the session to child loaders via `beforeLoad`.
- */
+/** Guards child routes: redirects to sign-in when no session; exposes session via `beforeLoad`. */
 export const Route = createFileRoute('/_authed')({
   beforeLoad: async () => {
     const session = await getServerSession()

package/_stack/apps/tanstack-base/src/routes/api/auth/$.ts

@@ -1,4 +1,4 @@
-// Loads the TanStack Start augmentation that adds `server` to route options.
+// Loads the Start augmentation adding `server` to route options.
 
 import { createFileRoute } from '@tanstack/react-router'
 import type {} from '@tanstack/react-start'

package/_stack/apps/tanstack-base/src/routes/api.trpc.$.tsx

@@ -1,5 +1,4 @@
-// Loads the TanStack Start augmentation that adds `server` to route options
-// (so this server route typechecks even without other react-start imports).
+// Loads TanStack Start augmentation adding `server` to route options (typechecks without other react-start imports).
 
 import { createFileRoute } from '@tanstack/react-router'
 import type {} from '@tanstack/react-start'

package/_stack/apps/tanstack-base/src/server/better-auth/config.ts

@@ -43,7 +43,7 @@ export const auth = betterAuth({
   },
   socialProviders,
   user: {
-    // Extend the user with extra columns here (mirror them in auth.schema.ts):
+    // Add extra columns here (mirror in auth.schema.ts):
     // additionalFields: {
     //   role: { type: 'string', defaultValue: 'user', input: false },
     // },

package/_stack/apps/tanstack-base/src/server/better-auth/session.ts

@@ -3,14 +3,13 @@ import { getRequest } from '@tanstack/react-start/server'
 import { auth } from '.'
 
 /**
- * Server-function: resolves the better-auth session from the current request
- * headers. Use it in route loaders / `beforeLoad`.
+ * Server-fn resolving the better-auth session from request headers; use in
+ * loaders / `beforeLoad`.
  *
- * The server-only `getRequest` call lives INSIDE the handler on purpose: the
- * TanStack Start plugin extracts the handler server-side and strips this import
- * from the client bundle. A standalone module-scope helper that calls
- * `getRequest` would leak `@tanstack/react-start/server` into client code (it's
- * imported transitively by routes) and trip the import-protection plugin.
+ * `getRequest` is called INSIDE the handler on purpose: the Start plugin
+ * extracts handlers server-side and strips the import from the client bundle.
+ * Calling it at module scope would leak `@tanstack/react-start/server` into
+ * client code (routes import this transitively) and trip import-protection.
  */
 export const getServerSession = createServerFn({ method: 'GET' }).handler(() =>
   auth.api.getSession({ headers: getRequest().headers }),

package/_stack/apps/tanstack-base/src/server/db/schemas/index.ts

@@ -1,2 +1,2 @@
-// Barrel of every Drizzle schema. Add one `export *` line per `*.schema.ts`.
+// Drizzle schema barrel; one `export *` per `*.schema.ts`.
 export * from './auth.schema'

package/_stack/apps/tanstack-base/src/server/db/seed.ts

@@ -3,11 +3,11 @@ import { config } from 'dotenv'
 
 config({ path: ['.env.local', '.env'] })
 
-// Deterministic data across runs.
+// Deterministic across runs.
 faker.seed(42)
 
 async function main() {
-  // Import the db client and seed your tables here (idempotent), using faker:
+  // Seed your tables here (idempotent) via faker:
   //   const { db } = await import('~/server/db')
   //   await db.insert(user).values({
   //     id: faker.string.uuid(),

package/_stack/apps/tanstack-base/src/server/email/adapters/resend/index.ts

@@ -4,7 +4,7 @@ import { formatAddress } from '../../core/address'
 import { type MailerAdapter, MailerError, type RenderedMessage } from '../../core/port'
 import { ResendConfigSchema } from './config'
 
-/** Minimal structural view of the Resend client we depend on (eases testing). */
+/** Minimal structural view of the Resend client (eases testing). */
 export interface ResendClient {
   emails: {
     send(payload: ResendSendPayload): Promise<{
@@ -30,7 +30,7 @@ interface ResendSendPayload {
 
 export interface ResendAdapterOptions {
   apiKey: string
-  /** Inject a custom/mock client. Defaults to a real `Resend` instance. */
+  /** Custom/mock client; defaults to a real `Resend`. */
   client?: ResendClient
 }
 
@@ -39,7 +39,7 @@ function toAttachmentContent(content: Uint8Array | string): Buffer | string {
 }
 
 export function resendAdapter(options: ResendAdapterOptions): MailerAdapter {
-  // Validate config early so a missing key fails at construction, not at send().
+  // Validate early so a missing key fails at construction, not send().
   const config = v.parse(ResendConfigSchema, { apiKey: options.apiKey })
   const client: ResendClient =
     options.client ?? (new Resend(config.apiKey) as unknown as ResendClient)

package/_stack/apps/tanstack-base/src/server/email/core/address.ts

@@ -2,7 +2,7 @@ import type { MailAddress, MailRecipient } from './port'
 
 const ADDRESS_RE = /^\s*(.*?)\s*<([^>]+)>\s*$/
 
-/** Coerce a recipient into a structured {@link MailAddress}. */
+/** Coerce a recipient to a structured {@link MailAddress}. */
 export function normalizeAddress(input: MailRecipient): MailAddress {
   if (typeof input !== 'string') return input
   const match = input.match(ADDRESS_RE)
@@ -10,12 +10,12 @@ export function normalizeAddress(input: MailRecipient): MailAddress {
   return { email: input.trim() }
 }
 
-/** Coerce a single recipient or list into a normalized array. */
+/** Coerce a recipient or list to a normalized array. */
 export function normalizeRecipients(input: MailRecipient | MailRecipient[]): MailAddress[] {
   return (Array.isArray(input) ? input : [input]).map(normalizeAddress)
 }
 
-/** Render an address back to an RFC-style string (`Name <email>`). */
+/** Render an address to RFC-style `Name <email>`. */
 export function formatAddress(address: MailAddress): string {
   return address.name ? `${address.name} <${address.email}>` : address.email
 }

package/_stack/apps/tanstack-base/src/server/email/core/port.ts

@@ -1,41 +1,37 @@
 import type { ReactElement } from 'react'
 
-/** A structured email address. */
+/** Structured email address. */
 export interface MailAddress {
   email: string
   name?: string
 }
 
-/**
- * A recipient, either as a plain string (`"hi@acme.com"` or
- * `"Acme <hi@acme.com>"`) or a structured {@link MailAddress}.
- */
+/** Recipient: string (`"hi@acme.com"` / `"Acme <hi@acme.com>"`) or {@link MailAddress}. */
 export type MailRecipient = string | MailAddress
 
 export interface MailAttachment {
   filename: string
-  /** Raw bytes or a base64 string. */
+  /** Raw bytes or base64 string. */
   content: Uint8Array | string
   contentType?: string
 }
 
 /**
- * A message as authored by application code. We never send raw HTML strings:
- * the body is always a React Email component, rendered to HTML + plain text by
- * the mailer before it reaches the adapter.
+ * Message as authored by app code. Never raw HTML: the body is always a React
+ * Email component, rendered to HTML + text by the mailer before the adapter.
  */
 export interface MailMessage {
   to: MailRecipient | MailRecipient[]
   subject: string
-  /** A React Email component. Rendered to HTML and plain text automatically. */
+  /** React Email component; rendered to HTML + text automatically. */
   react: ReactElement
-  /** Overrides the default `from` configured on the mailer. */
+  /** Overrides the mailer's default `from`. */
   from?: MailRecipient
   replyTo?: MailRecipient
   cc?: MailRecipient | MailRecipient[]
   bcc?: MailRecipient | MailRecipient[]
   headers?: Record<string, string>
-  /** Provider-agnostic key/value tags for analytics & filtering. */
+  /** Provider-agnostic tags for analytics & filtering. */
   tags?: Record<string, string>
   attachments?: MailAttachment[]
 }
@@ -45,18 +41,12 @@ export interface SentMail {
   id: string
 }
 
-/**
- * The port the application depends on. Swapping providers means swapping the
- * adapter passed to {@link createMailer}; this interface never changes.
- */
+/** The port the app depends on; swap providers via {@link createMailer}'s adapter — this never changes. */
 export interface Mailer {
   send(message: MailMessage): Promise<SentMail>
 }
 
-/**
- * The message shape an adapter receives: addresses are normalized and the body
- * is already rendered to `html` + `text`. Adapters do no rendering.
- */
+/** Shape an adapter receives: normalized addresses, body pre-rendered to `html` + `text`. Adapters don't render. */
 export interface RenderedMessage {
   to: MailAddress[]
   from: MailAddress
@@ -71,13 +61,13 @@ export interface RenderedMessage {
   attachments?: MailAttachment[]
 }
 
-/** The contract each provider implements. Kept intentionally tiny. */
+/** Contract each provider implements; intentionally tiny. */
 export interface MailerAdapter {
   readonly name: string
   send(message: RenderedMessage): Promise<SentMail>
 }
 
-/** Normalized error thrown by adapters so callers never catch provider types. */
+/** Normalized adapter error so callers never catch provider types. */
 export class MailerError extends Error {
   readonly adapter: string
 

package/_stack/apps/tanstack-base/src/server/email/core/render.ts

@@ -6,7 +6,7 @@ export interface RenderedBody {
   text: string
 }
 
-/** A function that turns a React Email component into HTML + plain text. */
+/** Turns a React Email component into HTML + plain text. */
 export type EmailRenderer = (react: ReactElement) => Promise<RenderedBody>
 
 /** Default renderer backed by `@react-email/render`. */

package/_stack/apps/tanstack-base/src/server/email/factory.ts

@@ -3,21 +3,20 @@ import type { Mailer, MailerAdapter, MailRecipient, RenderedMessage } from './co
 import { type EmailRenderer, renderEmail } from './core/render'
 
 export interface CreateMailerOptions {
-  /** The provider implementation (Resend, Brevo, …). */
+  /** Provider impl (Resend, Brevo, …). */
   adapter: MailerAdapter
-  /** Default sender used when a message omits `from`. */
+  /** Default sender when a message omits `from`. */
   from: MailRecipient
-  /** Override the React Email renderer (mostly for tests). */
+  /** Override the renderer (mostly for tests). */
   render?: EmailRenderer
 }
 
 /**
- * Build a {@link Mailer}. This is the composition root: pick the adapter here,
- * the rest of the app depends only on the `Mailer` port.
+ * Build a {@link Mailer}. Composition root: pick the adapter here; the rest of
+ * the app depends only on the `Mailer` port.
  *
- * The mailer renders the React body to HTML + plain text, normalizes every
- * address, applies the default sender, then hands a {@link RenderedMessage} to
- * the adapter.
+ * Renders the React body to HTML + text, normalizes addresses, applies the
+ * default sender, then hands a {@link RenderedMessage} to the adapter.
  */
 export function createMailer(options: CreateMailerOptions): Mailer {
   const defaultFrom = normalizeAddress(options.from)

package/_stack/apps/tanstack-base/src/server/email/index.ts

@@ -11,7 +11,7 @@ function required(value: string | undefined, name: string): string {
   return value
 }
 
-// Lazy so the app boots without RESEND_API_KEY; the adapter is built on first send.
+// Lazy so the app boots without RESEND_API_KEY; adapter built on first send.
 let mailer: Mailer | null = null
 function getMailer(): Mailer {
   if (!mailer) {

package/_stack/packages/analytics/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@alfredmouelle/analytics",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@alfredmouelle/http": "workspace:*",
+    "posthog-node": "^5.38.2",
+    "valibot": "^1.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}

package/_stack/packages/analytics/src/adapters/noop/index.ts

@@ -0,0 +1,12 @@
+import type { AnalyticsPort } from '../../core/port.js'
+
+/** No-op analytics adapter (dev/tests/disabled); call sites still depend on the port. */
+export function noopAdapter(): AnalyticsPort {
+  return {
+    name: 'noop',
+    capture() {},
+    identify() {},
+    async flush() {},
+    async shutdown() {},
+  }
+}

package/_stack/packages/analytics/src/adapters/plausible/config.ts

@@ -0,0 +1,10 @@
+import * as v from 'valibot'
+
+export const PlausibleConfigSchema = v.object({
+  /** Site domain as registered in Plausible (e.g. `acme.com`). */
+  domain: v.pipe(v.string(), v.minLength(1, 'Plausible domain is required')),
+  /** Plausible host. Defaults to `https://plausible.io`. */
+  apiHost: v.optional(v.string()),
+})
+
+export type PlausibleConfig = v.InferOutput<typeof PlausibleConfigSchema>

package/_stack/packages/analytics/src/adapters/plausible/index.ts

@@ -0,0 +1,94 @@
+import { apiFetch } from '@alfredmouelle/http'
+import * as v from 'valibot'
+import type { AnalyticsPort, CaptureEvent } from '../../core/port.js'
+import { PlausibleConfigSchema } from './config.js'
+
+const DEFAULT_API_HOST = 'https://plausible.io'
+const DEFAULT_USER_AGENT = '@alfredmouelle/analytics (+https://plausible.io)'
+
+export interface PlausibleAdapterOptions {
+  /** Site domain as registered in Plausible (e.g. `acme.com`). */
+  domain: string
+  /** Plausible host. Defaults to `https://plausible.io`. */
+  apiHost?: string
+  /** Fallback page URL when an event has no `url`. */
+  defaultUrl?: string
+  /** User-Agent sent to Plausible; it derives the cookieless visitor id from UA + client IP, so use a realistic value. */
+  userAgent?: string
+  /** Inject a custom fetch (mock/scoped client). */
+  fetchImpl?: typeof globalThis.fetch
+  /** Called on fire-and-forget request failure; defaults to swallowing. */
+  onError?: (error: unknown) => void
+}
+
+interface PlausibleEventPayload {
+  name: string
+  domain: string
+  url: string
+  referrer?: string
+  props?: Record<string, unknown>
+}
+
+/**
+ * Plausible adapter via server-side Events API (`POST /api/event`). `capture` is
+ * fire-and-forget; requests are tracked so `flush`/`shutdown` drain them.
+ * Cookieless, no person profiles, so `identify` is a no-op; `distinctId` is
+ * forwarded as a `distinct_id` prop for visibility only (counting uses UA + IP).
+ * `url`/`referrer`/`ip` read from event `properties`; `url` falls back to `defaultUrl`.
+ */
+export function plausibleAdapter(options: PlausibleAdapterOptions): AnalyticsPort {
+  const config = v.parse(PlausibleConfigSchema, {
+    domain: options.domain,
+    apiHost: options.apiHost,
+  })
+  const apiHost = config.apiHost ?? DEFAULT_API_HOST
+  const userAgent = options.userAgent ?? DEFAULT_USER_AGENT
+  const defaultUrl = options.defaultUrl ?? `https://${config.domain}/`
+  const onError = options.onError ?? (() => {})
+  const pending = new Set<Promise<void>>()
+
+  function send(payload: PlausibleEventPayload, ip?: string): void {
+    const headers: Record<string, string> = { 'User-Agent': userAgent }
+    if (ip) headers['X-Forwarded-For'] = ip
+
+    const request = apiFetch('/api/event', {
+      method: 'POST',
+      baseUrl: apiHost,
+      headers,
+      body: payload,
+      parseAs: 'none',
+      fetchImpl: options.fetchImpl,
+    })
+      .then(() => {})
+      .catch(onError)
+
+    pending.add(request)
+    void request.finally(() => pending.delete(request))
+  }
+
+  return {
+    name: 'plausible',
+    capture(event: CaptureEvent) {
+      const { url, referrer, ip, ...rest } = (event.properties ?? {}) as Record<string, unknown>
+      send(
+        {
+          name: event.event,
+          domain: config.domain,
+          url: typeof url === 'string' ? url : defaultUrl,
+          referrer: typeof referrer === 'string' ? referrer : undefined,
+          props: { distinct_id: event.distinctId, ...rest },
+        },
+        typeof ip === 'string' ? ip : undefined,
+      )
+    },
+    identify() {
+      // Cookieless, no person profiles — nothing to do.
+    },
+    async flush() {
+      await Promise.all([...pending])
+    },
+    async shutdown() {
+      await Promise.all([...pending])
+    },
+  }
+}

package/_stack/packages/analytics/src/adapters/posthog/config.ts

@@ -0,0 +1,7 @@
+import * as v from 'valibot'
+
+export const PostHogConfigSchema = v.object({
+  apiKey: v.pipe(v.string(), v.minLength(1, 'POSTHOG_API_KEY is required')),
+})
+
+export type PostHogConfig = v.InferOutput<typeof PostHogConfigSchema>

package/_stack/packages/analytics/src/adapters/posthog/index.ts

@@ -0,0 +1,50 @@
+import { PostHog } from 'posthog-node'
+import * as v from 'valibot'
+import type { AnalyticsPort, CaptureEvent, IdentifyParams } from '../../core/port.js'
+import { PostHogConfigSchema } from './config.js'
+
+/** Minimal structural view of the PostHog client (eases testing). */
+export interface PostHogLike {
+  capture(payload: CaptureEvent): void
+  identify(payload: IdentifyParams): void
+  flush(): Promise<void>
+  shutdown(): Promise<void>
+}
+
+export interface PostHogAdapterOptions {
+  apiKey: string
+  /** PostHog host (defaults to PostHog's default). */
+  host?: string
+  /** Inject a custom/mock client; defaults to a real `PostHog`. */
+  client?: PostHogLike
+}
+
+export function posthogAdapter(options: PostHogAdapterOptions): AnalyticsPort {
+  // Validate early: missing key fails at construction, not at capture().
+  const config = v.parse(PostHogConfigSchema, { apiKey: options.apiKey })
+  const client: PostHogLike =
+    options.client ?? (new PostHog(config.apiKey, { host: options.host }) as unknown as PostHogLike)
+
+  return {
+    name: 'posthog',
+    capture(event: CaptureEvent) {
+      client.capture({
+        distinctId: event.distinctId,
+        event: event.event,
+        properties: event.properties,
+      })
+    },
+    identify(params: IdentifyParams) {
+      client.identify({
+        distinctId: params.distinctId,
+        properties: params.properties,
+      })
+    },
+    flush() {
+      return client.flush()
+    },
+    shutdown() {
+      return client.shutdown()
+    },
+  }
+}

package/_stack/packages/analytics/src/core/port.ts

@@ -0,0 +1,30 @@
+/** Analytics event to capture. Fire-and-forget. */
+export interface CaptureEvent {
+  /** Event name, e.g. `'user_signed_up'`. */
+  event: string
+  /** Stable user/actor id. */
+  distinctId: string
+  /** Event metadata. */
+  properties?: Record<string, unknown>
+}
+
+/** Set/update properties on a user/actor. Fire-and-forget. */
+export interface IdentifyParams {
+  /** Stable user/actor id. */
+  distinctId: string
+  /** Person properties to set. */
+  properties?: Record<string, unknown>
+}
+
+/**
+ * App-facing port; swap adapters at the composition root, never this interface.
+ * `capture`/`identify` are fire-and-forget (like PostHog SDK): enqueue and return.
+ * `flush` drains pending events; `shutdown` flushes + releases before exit.
+ */
+export interface AnalyticsPort {
+  readonly name: string
+  capture(event: CaptureEvent): void
+  identify(params: IdentifyParams): void
+  flush(): Promise<void>
+  shutdown(): Promise<void>
+}

package/_stack/packages/analytics/src/index.ts

@@ -0,0 +1,17 @@
+export { noopAdapter } from './adapters/noop/index.js'
+export { type PlausibleConfig, PlausibleConfigSchema } from './adapters/plausible/config.js'
+export {
+  type PlausibleAdapterOptions,
+  plausibleAdapter,
+} from './adapters/plausible/index.js'
+export { type PostHogConfig, PostHogConfigSchema } from './adapters/posthog/config.js'
+export {
+  type PostHogAdapterOptions,
+  type PostHogLike,
+  posthogAdapter,
+} from './adapters/posthog/index.js'
+export type {
+  AnalyticsPort,
+  CaptureEvent,
+  IdentifyParams,
+} from './core/port.js'