@alfredmouelle/create-stack 0.1.2 → 0.2.0

package/_stack/packages/error-tracking/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@alfredmouelle/error-tracking",
+  "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": {
+    "@sentry/node": "^10.59.0",
+    "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/error-tracking/src/adapters/console/index.ts

@@ -0,0 +1,43 @@
+import type {
+  Breadcrumb,
+  CaptureContext,
+  ErrorTrackingPort,
+  ErrorUser,
+  SeverityLevel,
+} from '../../core/port.js'
+
+export interface ConsoleAdapterOptions {
+  /** Max breadcrumbs kept in memory (oldest dropped). Default 20. */
+  maxBreadcrumbs?: number
+}
+
+/** Dev/test adapter logging to console; user + breadcrumb state kept in-memory (no transport). */
+export function consoleAdapter(options: ConsoleAdapterOptions = {}): ErrorTrackingPort {
+  const maxBreadcrumbs = options.maxBreadcrumbs ?? 20
+  let user: ErrorUser | null = null
+  const breadcrumbs: Breadcrumb[] = []
+
+  function state() {
+    return { user, breadcrumbs }
+  }
+
+  return {
+    name: 'console',
+    captureException(error: unknown, context?: CaptureContext) {
+      console.error('[error-tracking] exception', error, { ...context, ...state() })
+    },
+    captureMessage(message: string, level: SeverityLevel = 'info') {
+      console.error('[error-tracking] message', { message, level, ...state() })
+    },
+    setUser(next: ErrorUser | null) {
+      user = next
+    },
+    addBreadcrumb(breadcrumb: Breadcrumb) {
+      breadcrumbs.push(breadcrumb)
+      if (breadcrumbs.length > maxBreadcrumbs) breadcrumbs.shift()
+    },
+    flush() {
+      return Promise.resolve(true)
+    },
+  }
+}

package/_stack/packages/error-tracking/src/adapters/sentry/config.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const SentryConfigSchema = v.object({
+  dsn: v.pipe(v.string(), v.minLength(1, 'SENTRY_DSN is required')),
+  environment: v.optional(v.string()),
+})
+
+export type SentryConfig = v.InferOutput<typeof SentryConfigSchema>

package/_stack/packages/error-tracking/src/adapters/sentry/index.ts

@@ -0,0 +1,72 @@
+import * as Sentry from '@sentry/node'
+import * as v from 'valibot'
+import type {
+  Breadcrumb,
+  CaptureContext,
+  ErrorTrackingPort,
+  ErrorUser,
+  SeverityLevel,
+} from '../../core/port.js'
+import { SentryConfigSchema } from './config.js'
+
+/** Minimal structural view of the Sentry namespace (eases testing). */
+export interface SentryCaptureContext {
+  tags?: Record<string, string>
+  extra?: Record<string, unknown>
+  level?: SeverityLevel
+}
+
+export interface SentryLike {
+  init(options: { dsn: string; environment?: string }): void
+  captureException(error: unknown, context?: SentryCaptureContext): void
+  captureMessage(message: string, level?: SeverityLevel): void
+  setUser(user: ErrorUser | null): void
+  addBreadcrumb(breadcrumb: Breadcrumb): void
+  flush(timeoutMs?: number): Promise<boolean>
+}
+
+export interface SentryAdapterOptions {
+  dsn: string
+  environment?: string
+  /** Inject a custom/mock client; defaults to the real `@sentry/node`. */
+  client?: SentryLike
+  /** Skip the implicit `Sentry.init` (e.g. init happens elsewhere). */
+  init?: boolean
+}
+
+export function sentryAdapter(options: SentryAdapterOptions): ErrorTrackingPort {
+  // Validate early: missing DSN fails at construction, not at capture().
+  const config = v.parse(SentryConfigSchema, {
+    dsn: options.dsn,
+    environment: options.environment,
+  })
+  const client: SentryLike = options.client ?? (Sentry as unknown as SentryLike)
+
+  // Only init the real namespace; injected clients are assumed already wired.
+  if (options.init !== false && !options.client) {
+    client.init({ dsn: config.dsn, environment: config.environment })
+  }
+
+  return {
+    name: 'sentry',
+    captureException(error: unknown, context?: CaptureContext) {
+      client.captureException(error, {
+        tags: context?.tags,
+        extra: context?.extra,
+        level: context?.level,
+      })
+    },
+    captureMessage(message: string, level?: SeverityLevel) {
+      client.captureMessage(message, level)
+    },
+    setUser(user: ErrorUser | null) {
+      client.setUser(user)
+    },
+    addBreadcrumb(breadcrumb: Breadcrumb) {
+      client.addBreadcrumb(breadcrumb)
+    },
+    flush(timeoutMs?: number) {
+      return client.flush(timeoutMs)
+    },
+  }
+}

package/_stack/packages/error-tracking/src/core/port.ts

@@ -0,0 +1,39 @@
+/** Captured-event severity, matching common provider levels. */
+export type SeverityLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug'
+
+/** User an event is associated with. */
+export interface ErrorUser {
+  id?: string
+  email?: string
+  username?: string
+}
+
+/** Trail of events leading up to an error, for debugging. */
+export interface Breadcrumb {
+  message: string
+  category?: string
+  level?: SeverityLevel
+  data?: Record<string, unknown>
+}
+
+/** Extra context attached to a single capture. */
+export interface CaptureContext {
+  tags?: Record<string, string>
+  extra?: Record<string, unknown>
+  level?: SeverityLevel
+}
+
+/** App-facing port; swap adapters at the composition root, never this interface. */
+export interface ErrorTrackingPort {
+  readonly name: string
+  /** Report an error (or any thrown value) with optional context. */
+  captureException(error: unknown, context?: CaptureContext): void
+  /** Report a standalone message at severity (default `info`). */
+  captureMessage(message: string, level?: SeverityLevel): void
+  /** Associate subsequent events with a user; `null` clears. */
+  setUser(user: ErrorUser | null): void
+  /** Record a breadcrumb for subsequent events. */
+  addBreadcrumb(breadcrumb: Breadcrumb): void
+  /** Flush buffered events; resolves `true` if all sent in time. */
+  flush(timeoutMs?: number): Promise<boolean>
+}

package/_stack/packages/error-tracking/src/index.ts

@@ -0,0 +1,14 @@
+export { type ConsoleAdapterOptions, consoleAdapter } from './adapters/console/index.js'
+export { type SentryConfig, SentryConfigSchema } from './adapters/sentry/config.js'
+export {
+  type SentryAdapterOptions,
+  type SentryLike,
+  sentryAdapter,
+} from './adapters/sentry/index.js'
+export type {
+  Breadcrumb,
+  CaptureContext,
+  ErrorTrackingPort,
+  ErrorUser,
+  SeverityLevel,
+} from './core/port.js'

package/_stack/packages/http/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@alfredmouelle/http",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}

package/_stack/packages/http/src/api.ts

@@ -0,0 +1,373 @@
+export type ApiFetchMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'
+
+export type ApiParseMode = 'json' | 'text' | 'blob' | 'arrayBuffer' | 'none'
+
+export type QueryValue = string | number | boolean | null | undefined
+
+export type QueryParams = Record<string, QueryValue | QueryValue[]> | URLSearchParams
+
+export interface ApiFetchOptions {
+  method?: ApiFetchMethod
+  baseUrl?: string
+  query?: QueryParams
+  body?: unknown
+  headers?: HeadersInit
+  signal?: AbortSignal
+  timeoutMs?: number
+  parseAs?: ApiParseMode
+  credentials?: RequestCredentials
+  cache?: RequestCache
+  init?: RequestInit
+  /** Inject custom fetch (mock in tests, scoped client in adapters). */
+  fetchImpl?: typeof globalThis.fetch
+}
+
+export class ApiFetchError extends Error {
+  readonly status: number
+  readonly statusText: string
+  readonly url: string
+  readonly method: string
+  readonly body: unknown
+  readonly response?: Response
+
+  constructor(
+    message: string,
+    details: {
+      status: number
+      statusText: string
+      url: string
+      method: string
+      body?: unknown
+      response?: Response
+      cause?: unknown
+    },
+  ) {
+    super(message, { cause: details.cause })
+    this.name = 'ApiFetchError'
+    this.status = details.status
+    this.statusText = details.statusText
+    this.url = details.url
+    this.method = details.method
+    this.body = details.body
+    this.response = details.response
+  }
+
+  get isNetworkError(): boolean {
+    return this.status === 0
+  }
+
+  get isTimeout(): boolean {
+    return this.status === 408 || this.status === 504
+  }
+
+  get serverMessage(): string | undefined {
+    const body = this.body
+    if (typeof body === 'string') return body.trim() || undefined
+    if (body && typeof body === 'object') {
+      const record = body as Record<string, unknown>
+      for (const key of ['error', 'message', 'detail']) {
+        const value = record[key]
+        if (typeof value === 'string' && value.trim()) return value
+      }
+    }
+    return undefined
+  }
+}
+
+export function isApiFetchError(error: unknown): error is ApiFetchError {
+  return error instanceof ApiFetchError
+}
+
+export class ApiParseError extends Error {
+  readonly url: string
+  readonly method: string
+  readonly status: number
+  readonly raw: string
+  readonly response: Response
+
+  constructor(
+    message: string,
+    details: {
+      url: string
+      method: string
+      status: number
+      raw: string
+      response: Response
+      cause?: unknown
+    },
+  ) {
+    super(message, { cause: details.cause })
+    this.name = 'ApiParseError'
+    this.url = details.url
+    this.method = details.method
+    this.status = details.status
+    this.raw = details.raw
+    this.response = details.response
+  }
+}
+
+export function isApiParseError(error: unknown): error is ApiParseError {
+  return error instanceof ApiParseError
+}
+
+function isCancellation(error: unknown): boolean {
+  return (
+    error instanceof DOMException && (error.name === 'AbortError' || error.name === 'TimeoutError')
+  )
+}
+
+function isTimeoutAbort(error: unknown): boolean {
+  return error instanceof DOMException && error.name === 'TimeoutError'
+}
+
+function timeoutError(
+  error: unknown,
+  url: string,
+  method: string,
+  response?: Response,
+): ApiFetchError {
+  return new ApiFetchError(`${method} ${url} timed out`, {
+    status: 408,
+    statusText: 'Request Timeout',
+    url,
+    method,
+    response,
+    cause: error,
+  })
+}
+
+function isRawBody(body: unknown): body is BodyInit {
+  return (
+    typeof body === 'string' ||
+    body instanceof FormData ||
+    body instanceof URLSearchParams ||
+    body instanceof Blob ||
+    body instanceof ArrayBuffer ||
+    ArrayBuffer.isView(body) ||
+    (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream)
+  )
+}
+
+function toSearchParams(query: QueryParams): URLSearchParams {
+  if (query instanceof URLSearchParams) return query
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(query)) {
+    if (value === null || value === undefined) continue
+    const values = Array.isArray(value) ? value : [value]
+    for (const item of values) {
+      if (item === null || item === undefined) continue
+      params.append(key, String(item))
+    }
+  }
+  return params
+}
+
+function buildUrl(
+  path: string,
+  baseUrl: string | undefined,
+  query: QueryParams | undefined,
+): string {
+  const isAbsolute = /^[a-z][a-z\d+.-]*:\/\//i.test(path)
+  const base = baseUrl ? baseUrl.replace(/\/+$/, '') : ''
+  let url = isAbsolute || !base ? path : `${base}${path.startsWith('/') ? path : `/${path}`}`
+
+  if (query) {
+    const qs = toSearchParams(query).toString()
+    if (qs) url += `${url.includes('?') ? '&' : '?'}${qs}`
+  }
+  return url
+}
+
+function resolveSignal(
+  signal: AbortSignal | undefined,
+  timeoutMs: number | undefined,
+): AbortSignal | undefined {
+  if (timeoutMs === undefined) return signal
+  const timeout = AbortSignal.timeout(timeoutMs)
+  if (!signal) return timeout
+  if (typeof AbortSignal.any === 'function') {
+    return AbortSignal.any([signal, timeout])
+  }
+  return signal
+}
+
+function inferParseMode(response: Response): ApiParseMode {
+  const contentType = response.headers.get('content-type') ?? ''
+  if (contentType.includes('application/json') || contentType.includes('+json')) {
+    return 'json'
+  }
+  if (!contentType || contentType.startsWith('text/')) return 'text'
+  return 'blob'
+}
+
+async function parseResponse<T>(
+  response: Response,
+  parseAs: ApiParseMode | undefined,
+  url: string,
+  method: string,
+): Promise<T> {
+  if (parseAs === 'none' || response.status === 204 || response.status === 205) {
+    return undefined as T
+  }
+  const mode = parseAs ?? inferParseMode(response)
+  try {
+    switch (mode) {
+      case 'json': {
+        const text = await response.text()
+        if (!text) return undefined as T
+        try {
+          return JSON.parse(text) as T
+        } catch (error) {
+          throw new ApiParseError(`${method} ${url}: invalid JSON response`, {
+            url,
+            method,
+            status: response.status,
+            raw: text,
+            response,
+            cause: error,
+          })
+        }
+      }
+      case 'text':
+        return (await response.text()) as T
+      case 'blob':
+        return (await response.blob()) as T
+      case 'arrayBuffer':
+        return (await response.arrayBuffer()) as T
+      default:
+        return undefined as T
+    }
+  } catch (error) {
+    if (error instanceof ApiParseError) throw error
+    if (isTimeoutAbort(error)) throw timeoutError(error, url, method, response)
+    if (isCancellation(error)) throw error
+    throw new ApiParseError(`${method} ${url}: failed to read response body`, {
+      url,
+      method,
+      status: response.status,
+      raw: '',
+      response,
+      cause: error,
+    })
+  }
+}
+
+async function parseErrorBody(response: Response): Promise<unknown> {
+  try {
+    const text = await response.text()
+    if (!text) return undefined
+    const contentType = response.headers.get('content-type') ?? ''
+    if (contentType.includes('json')) {
+      try {
+        return JSON.parse(text)
+      } catch {
+        return text
+      }
+    }
+    return text
+  } catch {
+    return undefined
+  }
+}
+
+function buildRequestHeaders(
+  headers: HeadersInit | undefined,
+  initHeaders: HeadersInit | undefined,
+  parseAs: ApiParseMode | undefined,
+): Headers {
+  const requestHeaders = new Headers(initHeaders)
+  if (headers) {
+    new Headers(headers).forEach((value, key) => {
+      requestHeaders.set(key, value)
+    })
+  }
+  if (!requestHeaders.has('Accept') && parseAs !== 'blob' && parseAs !== 'arrayBuffer') {
+    requestHeaders.set('Accept', 'application/json')
+  }
+  return requestHeaders
+}
+
+function buildRequestBody(
+  body: unknown,
+  method: ApiFetchMethod,
+  requestHeaders: Headers,
+): BodyInit | undefined {
+  const sendsBody = body !== undefined && body !== null
+  if (!sendsBody || method === 'GET' || method === 'HEAD') return undefined
+  if (isRawBody(body)) return body
+  if (!requestHeaders.has('Content-Type')) {
+    requestHeaders.set('Content-Type', 'application/json')
+  }
+  return JSON.stringify(body)
+}
+
+/**
+ * Typed `fetch` wrapper: URL/query building, JSON encoding, timeouts,
+ * content-negotiated parsing, `ApiFetchError`/`ApiParseError` on failure.
+ * Non-2xx throws.
+ */
+export async function apiFetch<T = unknown>(
+  path: string,
+  options: ApiFetchOptions = {},
+): Promise<T> {
+  const {
+    method = 'GET',
+    baseUrl,
+    query,
+    body,
+    headers,
+    signal,
+    timeoutMs,
+    parseAs,
+    credentials,
+    cache,
+    init,
+    fetchImpl,
+  } = options
+
+  const doFetch = fetchImpl ?? globalThis.fetch
+  const url = buildUrl(path, baseUrl, query)
+  const requestHeaders = buildRequestHeaders(headers, init?.headers, parseAs)
+  const requestBody = buildRequestBody(body, method, requestHeaders)
+
+  const userSignal = signal ?? init?.signal ?? undefined
+  const requestInit: RequestInit = { ...init }
+  requestInit.method = method
+  requestInit.headers = requestHeaders
+  requestInit.signal = resolveSignal(userSignal, timeoutMs)
+  if (method === 'GET' || method === 'HEAD') {
+    requestInit.body = undefined
+  } else if (requestBody !== undefined) {
+    requestInit.body = requestBody
+  }
+  if (credentials !== undefined) requestInit.credentials = credentials
+  if (cache !== undefined) requestInit.cache = cache
+
+  let response: Response
+  try {
+    response = await doFetch(url, requestInit)
+  } catch (error) {
+    if (isTimeoutAbort(error)) throw timeoutError(error, url, method)
+    if (isCancellation(error)) throw error
+    throw new ApiFetchError(`${method} ${url} failed: network error`, {
+      status: 0,
+      statusText: '',
+      url,
+      method,
+      cause: error,
+    })
+  }
+
+  if (!response.ok) {
+    throw new ApiFetchError(`${method} ${url} → ${response.status} ${response.statusText}`.trim(), {
+      status: response.status,
+      statusText: response.statusText,
+      url,
+      method,
+      body: await parseErrorBody(response),
+      response,
+    })
+  }
+
+  return parseResponse<T>(response, parseAs, url, method)
+}

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

@@ -0,0 +1,14 @@
+export {
+  ApiFetchError,
+  type ApiFetchMethod,
+  type ApiFetchOptions,
+  ApiParseError,
+  type ApiParseMode,
+  apiFetch,
+  isApiFetchError,
+  isApiParseError,
+  type QueryParams,
+  type QueryValue,
+} from './api.js'
+export { error, json, noContent, text } from './responses.js'
+export type { FetchHandler, WebhookHandler } from './types.js'

package/_stack/packages/http/src/responses.ts

@@ -0,0 +1,25 @@
+/** JSON `Response` with correct content-type. */
+export function json(data: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(data), {
+    ...init,
+    headers: { 'content-type': 'application/json', ...init.headers },
+  })
+}
+
+/** `204 No Content` — canonical webhook ack. */
+export function noContent(init: ResponseInit = {}): Response {
+  return new Response(null, { status: 204, ...init })
+}
+
+/** Plain-text `Response`. */
+export function text(body: string, init: ResponseInit = {}): Response {
+  return new Response(body, {
+    ...init,
+    headers: { 'content-type': 'text/plain; charset=utf-8', ...init.headers },
+  })
+}
+
+/** JSON error envelope. */
+export function error(message: string, status = 400, init: ResponseInit = {}): Response {
+  return json({ error: message }, { ...init, status })
+}

package/_stack/packages/http/src/types.ts

@@ -0,0 +1,9 @@
+/**
+ * Web Fetch `Request -> Response` handler. Next.js route handlers and TanStack
+ * Start server routes both speak it, so HTTP surfaces (webhooks, callbacks)
+ * target this type; mounting is a one-line shim per framework.
+ */
+export type FetchHandler = (request: Request) => Response | Promise<Response>
+
+/** Alias of {@link FetchHandler}; documents intent at call sites. */
+export type WebhookHandler = FetchHandler

package/_stack/packages/jobs/capability.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "jobs",
+  "description": "Background jobs / events behind a swappable port. Event-driven: define jobs against named events and trigger them; the adapter handles delivery and execution.",
+  "port": "src/core/port.ts",
+  "defaultAdapter": "inngest",
+  "adapters": {
+    "inngest": {
+      "deps": ["inngest"],
+      "env": ["INNGEST_EVENT_KEY", "INNGEST_SIGNING_KEY"],
+      "files": ["src/adapters/inngest"]
+    },
+    "trigger": {
+      "deps": ["@trigger.dev/sdk"],
+      "env": ["TRIGGER_SECRET_KEY"],
+      "files": ["src/adapters/trigger"]
+    },
+    "memory": {
+      "deps": [],
+      "env": [],
+      "files": ["src/adapters/memory"]
+    }
+  },
+  "sharedDeps": ["valibot"],
+  "sharedFiles": ["src/core", "src/index.ts"]
+}