@alfredmouelle/create-stack 0.1.1 → 0.2.0

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/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@alfredmouelle/jobs",
+  "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:*",
+    "@trigger.dev/sdk": "^4.4.6",
+    "inngest": "^4.7.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/jobs/src/adapters/inngest/config.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const InngestConfigSchema = v.object({
+  id: v.pipe(v.string(), v.minLength(1, 'Inngest app id is required')),
+  eventKey: v.optional(v.string()),
+})
+
+export type InngestConfig = v.InferOutput<typeof InngestConfigSchema>

package/_stack/packages/jobs/src/adapters/inngest/index.ts

@@ -0,0 +1,93 @@
+import type { FetchHandler } from '@alfredmouelle/http'
+import { Inngest } from 'inngest'
+import * as v from 'valibot'
+import type { JobDefinition, JobEvent, JobsPort } from '../../core/port.js'
+import { JobsError } from '../../core/port.js'
+import { InngestConfigSchema } from './config.js'
+
+/** Opaque Inngest function from `createFunction`. */
+export type InngestFunction = unknown
+
+/** Structural view of the Inngest client; real `Inngest` satisfies it, tests mock it. */
+export interface InngestLike {
+  send(payload: { name: string; data: unknown }): Promise<unknown>
+  createFunction(
+    config: { id: string },
+    trigger: { event: string },
+    handler: (ctx: { event: { name: string; data: unknown } }) => Promise<void> | void,
+  ): InngestFunction
+}
+
+export interface InngestAdapterOptions {
+  /** Inngest app id (`new Inngest({ id })`). */
+  id: string
+  /** Inject custom/mock client. Defaults to real `Inngest`. */
+  client?: InngestLike
+  /** Event key for sending in production. */
+  eventKey?: string
+}
+
+export interface InngestJobsAdapter extends JobsPort {
+  /** Functions from `defineJob`, for Inngest's `serve`. */
+  readonly functions: InngestFunction[]
+  /** Underlying client for advanced use (steps, cron, concurrency, …). */
+  readonly client: InngestLike
+}
+
+export function inngestAdapter(options: InngestAdapterOptions): InngestJobsAdapter {
+  // Validate early: bad id fails at construction, not trigger().
+  const config = v.parse(InngestConfigSchema, { id: options.id, eventKey: options.eventKey })
+  const client: InngestLike =
+    options.client ??
+    (new Inngest({ id: config.id, eventKey: config.eventKey }) as unknown as InngestLike)
+
+  const functions: InngestFunction[] = []
+
+  return {
+    name: 'inngest',
+    functions,
+    client,
+    defineJob<T>(def: JobDefinition<T>): JobDefinition<T> {
+      const fn = client.createFunction({ id: def.id }, { event: def.event }, ({ event }) =>
+        def.handler(event as JobEvent<T>),
+      )
+      functions.push(fn)
+      return def
+    },
+    async trigger<T>(event: JobEvent<T>): Promise<void> {
+      try {
+        await client.send({ name: event.name, data: event.data })
+      } catch (cause) {
+        throw new JobsError('Failed to send event to Inngest', { adapter: 'inngest', cause })
+      }
+    },
+  }
+}
+
+/** Collect functions for `serve({ client, functions })`. */
+export function inngestFunctions(adapter: InngestJobsAdapter): InngestFunction[] {
+  return adapter.functions
+}
+
+/**
+ * Inngest's framework-agnostic `serve` (e.g. `inngest/edge`). Loosely typed so
+ * the real `serve` (richer options than our `InngestLike`) is accepted.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: accepts the real serve whose options are richer than InngestLike
+export type InngestServe = (options: any) => FetchHandler
+
+/**
+ * {@link FetchHandler} serving the adapter's functions. Pass Inngest's `serve`
+ * (from `inngest/edge`); the handler mounts in Next.js or TanStack Start unchanged.
+ */
+export function inngestServeHandler<TServe extends InngestServe>(
+  adapter: InngestJobsAdapter,
+  serve: TServe,
+  options: { signingKey?: string } = {},
+): FetchHandler {
+  return serve({
+    client: adapter.client,
+    functions: adapter.functions,
+    signingKey: options.signingKey,
+  } as Parameters<TServe>[0])
+}

package/_stack/packages/jobs/src/adapters/memory/index.ts

@@ -0,0 +1,31 @@
+import type { JobDefinition, JobEvent, JobsPort } from '../../core/port.js'
+
+export interface MemoryJobsAdapter extends JobsPort {
+  /** Registered jobs, keyed by subscribed event name. */
+  readonly jobs: ReadonlyMap<string, JobDefinition[]>
+}
+
+/**
+ * In-process jobs adapter for dev/tests. `trigger` runs every matching handler
+ * inline (awaiting async) — no queue, no network. Unit-test jobs without Inngest.
+ */
+export function memoryAdapter(): MemoryJobsAdapter {
+  const jobs = new Map<string, JobDefinition[]>()
+
+  return {
+    name: 'memory',
+    jobs,
+    defineJob<T>(def: JobDefinition<T>): JobDefinition<T> {
+      const existing = jobs.get(def.event) ?? []
+      existing.push(def as JobDefinition)
+      jobs.set(def.event, existing)
+      return def
+    },
+    async trigger<T>(event: JobEvent<T>): Promise<void> {
+      const handlers = jobs.get(event.name) ?? []
+      for (const def of handlers) {
+        await def.handler(event)
+      }
+    },
+  }
+}

package/_stack/packages/jobs/src/adapters/trigger/config.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const TriggerDevConfigSchema = v.object({
+  /** Trigger auth key. Falls back to `TRIGGER_SECRET_KEY`. */
+  secretKey: v.optional(v.string()),
+})
+
+export type TriggerDevConfig = v.InferOutput<typeof TriggerDevConfigSchema>

package/_stack/packages/jobs/src/adapters/trigger/index.ts

@@ -0,0 +1,85 @@
+import { configure, task, tasks } from '@trigger.dev/sdk'
+import * as v from 'valibot'
+import type { JobDefinition, JobEvent, JobsPort } from '../../core/port.js'
+import { JobsError } from '../../core/port.js'
+import { TriggerDevConfigSchema } from './config.js'
+
+/** Opaque Trigger.dev task from `task()`. */
+export type TriggerTask = unknown
+
+/** Structural view of the Trigger.dev SDK; real `task`/`tasks.trigger` satisfy it, tests mock it. */
+export interface TriggerDevLike {
+  task(config: { id: string; run: (payload: unknown) => Promise<void> | void }): TriggerTask
+  trigger(id: string, payload: unknown): Promise<unknown>
+}
+
+export interface TriggerDevAdapterOptions {
+  /** Trigger auth key. Defaults to `TRIGGER_SECRET_KEY`. */
+  secretKey?: string
+  /** Inject custom/mock SDK. Defaults to real `@trigger.dev/sdk`. */
+  client?: TriggerDevLike
+}
+
+export interface TriggerDevJobsAdapter extends JobsPort {
+  /** Tasks from `defineJob`, to re-export from your Trigger.dev `dirs`. */
+  readonly tasks: TriggerTask[]
+}
+
+/** Bridge real SDK to {@link TriggerDevLike}; richer signatures narrowed here. */
+function defaultClient(secretKey?: string): TriggerDevLike {
+  if (secretKey) configure({ secretKey })
+  return {
+    task: task as unknown as TriggerDevLike['task'],
+    trigger: (id, payload) =>
+      (tasks.trigger as (id: string, payload: unknown) => Promise<unknown>)(id, payload),
+  }
+}
+
+/**
+ * Trigger.dev jobs adapter. Each {@link JobDefinition} becomes a task; `trigger`
+ * routes an event to every task subscribed to its `name`.
+ *
+ * No event bus (tasks trigger by id), so the adapter keeps an event → task-ids
+ * map and fans out on `trigger`. Created tasks collect on `adapter.tasks` for
+ * re-export from a file under your `dirs` (how the CLI discovers them).
+ */
+export function triggerDevAdapter(options: TriggerDevAdapterOptions = {}): TriggerDevJobsAdapter {
+  const config = v.parse(TriggerDevConfigSchema, { secretKey: options.secretKey })
+  const client: TriggerDevLike = options.client ?? defaultClient(config.secretKey)
+
+  const createdTasks: TriggerTask[] = []
+  // event name -> subscribed task ids
+  const routes = new Map<string, string[]>()
+
+  return {
+    name: 'trigger.dev',
+    tasks: createdTasks,
+    defineJob<T>(def: JobDefinition<T>): JobDefinition<T> {
+      const created = client.task({
+        id: def.id,
+        run: (payload) => def.handler({ name: def.event, data: payload } as JobEvent<T>),
+      })
+      createdTasks.push(created)
+      const ids = routes.get(def.event) ?? []
+      ids.push(def.id)
+      routes.set(def.event, ids)
+      return def
+    },
+    async trigger<T>(event: JobEvent<T>): Promise<void> {
+      const ids = routes.get(event.name) ?? []
+      try {
+        await Promise.all(ids.map((id) => client.trigger(id, event.data)))
+      } catch (cause) {
+        throw new JobsError('Failed to trigger Trigger.dev task', {
+          adapter: 'trigger.dev',
+          cause,
+        })
+      }
+    },
+  }
+}
+
+/** Collect tasks to re-export from a file under your `dirs`. */
+export function triggerDevTasks(adapter: TriggerDevJobsAdapter): TriggerTask[] {
+  return adapter.tasks
+}