@pikku/skills 0.12.22 → 0.12.26

package/skills/pikku-wiring/references/realtime.md

@@ -0,0 +1,265 @@
+# Pikku Realtime
+
+## 1. Declare your topics
+
+In your project's types file (e.g. `types/eventhub-topics.d.ts`):
+
+```ts
+import type { Todo } from '../src/schemas.js'
+
+export type EventHubTopics = {
+  'todo-created': { todo: Todo }
+  'todo-updated': { todo: Todo }
+  'todo-deleted': { todoId: string }
+}
+```
+
+Reference it in `application-types.d.ts` and instantiate it in `services.ts`:
+
+```ts
+// application-types.d.ts
+import type { EventHubService } from '@pikku/core/channel'
+import type { EventHubTopics } from './eventhub-topics.js'
+
+export interface SingletonServices extends CoreSingletonServices<Config> {
+  // `CoreSingletonServices` declares eventHub optional; re-declare it required
+  // so functions can use it without a `if (eventHub)` guard on every publish.
+  eventHub: EventHubService<EventHubTopics>
+}
+
+// services.ts
+import { LocalEventHubService } from '@pikku/core/channel'
+const eventHub = new LocalEventHubService<EventHubTopics>()
+```
+
+For multi-instance deployments use `CloudflareEventHubService` /
+`LambdaEventHubService` / `UWSEventHubService` instead — same interface.
+
+If a deployment genuinely has no eventHub, that belongs in `services.ts` (don't
+create the service there), not as an optional type every function has to guard —
+see `pikku-services`.
+
+## 2. Enable the server side
+
+```bash
+yarn pikku enable events
+```
+
+This sets `scaffold.events` in `pikku.config.json`. The next `pikku all` generates
+`events.gen.ts` in your scaffold dir, wiring (using whatever `eventHub` is in your
+singletons — you write neither by hand):
+
+- A WebSocket channel at `/events` handling `{action: 'subscribe' | 'unsubscribe', topic}` messages.
+- An SSE handler at `GET /events/:topic`.
+
+## 3. Generate the typed client
+
+Add to `pikku.config.json`:
+
+```jsonc
+{
+  "clientFiles": {
+    "realtimeFile": "packages/sdk/src/pikku/realtime.gen.ts",
+    // Optional: full type inference for subscribe/unsubscribe
+    "realtimeEventHubTopicsImport": "../../../functions/types/eventhub-topics.js#EventHubTopics",
+  },
+}
+```
+
+Run `pikku all` (or `pikku realtime` to regenerate just this file). Everything is
+on one class — both transports are methods, so switching from WebSocket to SSE is
+a one-word change, not a different import:
+
+```ts
+export class PikkuRealtime {
+  constructor(options?: {
+    reconnect?: boolean
+    reconnectDelayMs?: number
+    reconnectMaxDelayMs?: number
+  })
+  setPikkuFetch(fetch: PikkuFetch): void // server URL + auth come from here, not the constructor
+
+  // WebSocket at /events — many topics on one connection
+  subscribe<K extends keyof EventHubTopics>(
+    topic: K,
+    handler: (data: EventHubTopics[K]) => void
+  ): () => void
+  unsubscribe<K extends keyof EventHubTopics>(
+    topic: K,
+    handler?: (data: EventHubTopics[K]) => void
+  ): void
+
+  // SSE at GET /events/:topic — one EventSource per topic
+  subscribeToTopic<K extends keyof EventHubTopics>(
+    topic: K,
+    handler: (data: EventHubTopics[K]) => void
+  ): { close: () => void }
+
+  // generic escape hatches — see realtime-other-routes.md
+  subscribeToSSE<T>(
+    path: string,
+    handler: (data: T) => void
+  ): { close: () => void }
+  connectToChannel(
+    channelRoute: string,
+    protocols?: string | string[]
+  ): WebSocket
+
+  close(): void
+}
+```
+
+Without `realtimeEventHubTopicsImport`, the client falls back to
+`Record<string, unknown>` — usable but untyped. Set the import for full typed
+subscribe/unsubscribe.
+
+## 4. Publish events from a function
+
+The `/events` channel listens for client subscriptions; the eventHub fans out
+publishes:
+
+```ts
+publish(topic, channelId: string | null, data, isBinary?)
+```
+
+The middle argument is the channel to **skip**, not the one to send to — pass
+`null` to reach every subscriber, or the current `channel.channelId` when the
+originating connection has already applied the change locally and would otherwise
+render it twice.
+
+Envelope the payload as `{ topic, data }`: the generated client dispatches on the
+`topic` field, so a bare payload arrives but no handler fires.
+
+```ts
+import { pikkuFunc } from '#pikku/function'
+
+export const createTodo = pikkuFunc({
+  input: CreateTodoInput,
+  output: CreateTodoOutput,
+  func: async ({ kysely, eventHub }, data) => {
+    const todo = await kysely
+      .insertInto('todos')
+      .values(data)
+      .returningAll()
+      .executeTakeFirstOrThrow()
+
+    await eventHub.publish('todo-created', null, {
+      topic: 'todo-created',
+      data: { todo },
+    })
+    return { id: todo.id }
+  },
+})
+```
+
+A thin helper removes the duplication:
+
+```ts
+async function publishEvent<K extends keyof EventHubTopics>(
+  hub: EventHubService<EventHubTopics>,
+  topic: K,
+  data: EventHubTopics[K]
+) {
+  return hub.publish(topic, null, { topic, data })
+}
+// usage: await publishEvent(eventHub, 'todo-created', { todo })
+```
+
+## 5. Wire it up — share fetch with PikkuRPC
+
+`PikkuRealtime` mirrors `PikkuRPC`: it wraps the same `PikkuFetch`, so server URL +
+auth are configured **once** and shared across HTTP, RPC, and realtime transports.
+
+```tsx
+import { createPikku, PikkuProvider } from '@pikku/react'
+import { PikkuFetch } from './pikku/pikku-fetch.gen'
+import { PikkuRPC } from './pikku/pikku-rpc.gen'
+import { PikkuRealtime } from './pikku/realtime.gen'
+
+const pikku = createPikku(
+  PikkuFetch,
+  PikkuRPC,
+  PikkuRealtime, // pass the realtime class as the third arg
+  { serverUrl: apiUrl() } // shared env helper — see pikku-react
+)
+// pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch.
+
+createRoot(document.getElementById('root')!).render(
+  <PikkuProvider pikku={pikku}>
+    <App />
+  </PikkuProvider>
+)
+```
+
+Or wire manually:
+
+```ts
+const realtime = new PikkuRealtime()
+realtime.setPikkuFetch(pikku.fetch) // inherits serverUrl + auth
+```
+
+## 6. Subscribe from React
+
+Subscribe inside `useEffect` (never the render path, or you create a subscription
+per render). `subscribe` returns an unsubscribe function; SSE's `subscribeToTopic`
+returns a handle with `close()`:
+
+```tsx
+import { useEffect, useState } from 'react'
+
+function TodoList() {
+  const { realtime } = usePikku() // a hook over your context
+  const [todos, setTodos] = useState<Todo[]>([])
+
+  useEffect(() => {
+    // WebSocket multi-topic:
+    const off = realtime.subscribe('todo-created', ({ todo }) =>
+      setTodos((prev) => [...prev, todo])
+    )
+    return off
+
+    // Single-topic SSE (auto-cleanup on close) instead:
+    // const sub = realtime.subscribeToTopic('todo-created', ({ todo }) =>
+    //   setTodos((prev) => [...prev, todo]))
+    // return () => sub.close()
+  }, [realtime])
+
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Other SSE / WebSocket routes
+
+The same client also subscribes to generic `sse: true` routes and raw `wireChannel`
+sockets (`subscribeToSSE`, `connectToChannel`). See
+[realtime-other-routes.md](realtime-other-routes.md).
+
+## When to pick which transport
+
+| Need                                       | Use                         |
+| ------------------------------------------ | --------------------------- |
+| Many topics in one connection              | `realtime.subscribe`        |
+| Single live stream, simple cleanup         | `realtime.subscribeToTopic` |
+| Bidirectional (client also sends messages) | `realtime.subscribe`        |
+| WebSockets blocked by infra                | `realtime.subscribeToTopic` |
+
+Both auto-clean on the server (the eventHub's `onChannelClosed` hook unsubscribes
+all topics for the dead channel id). Don't write manual cleanup unless you're
+unsubscribing partway through a session.
+
+## What NOT to do
+
+- Don't call `eventHub.publish(topic, ..., rawData)` without the `{topic, data}`
+  envelope — clients use `topic` to dispatch handlers.
+- Don't create your own `/events` channel by hand — `pikku enable events` already
+  does it correctly with disconnect cleanup.
+- Don't subscribe inside the render path — use `useEffect`.
+- Don't subscribe to topics that don't exist in `EventHubTopics`. The generated
+  client's types prevent it; if you reach for `as any` to subscribe to a string,
+  declare the topic first.

package/skills/{pikku-rpc/SKILL.md → pikku-wiring/references/rpc.md}

@@ -1,37 +1,5 @@
----
-name: pikku-rpc
-description: >-
-  Use when making internal function-to-function calls within a Pikku app, composing functions, or
-  exposing RPC endpoints. Covers rpc.invoke, rpc.remote, rpc.exposed, and generated RPC client.
-  TRIGGER when: code uses wire.rpc or expose: true, user asks about calling one Pikku function
-  from another, function composition, or RPC endpoints. DO NOT TRIGGER when: user asks about HTTP
-  routes (use pikku-http) or addon cross-package calls (use pikku-addon).
-installGroups: [fabric]
----
-
 # Pikku RPC Wiring
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Call Pikku functions from other Pikku functions internally with full type safety. Use RPC to compose business logic without importing functions directly.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions and which could be called via RPC
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
 ## API Reference
 
 ### RPC Methods (on `wire.rpc`)

package/skills/{pikku-schedule/SKILL.md → pikku-wiring/references/scheduler.md}

@@ -1,45 +1,11 @@
----
-name: pikku-schedule
-description: >-
-  Use when adding scheduled tasks, recurring jobs, or cron-based automation to a Pikku app. Covers
-  wireScheduler, cron expressions, the scheduled task wire object, and scheduler middleware.
-  TRIGGER when: code uses wireScheduler, user asks about cron, scheduled tasks, recurring jobs, or
-  "run every X minutes/hours". DO NOT TRIGGER when: user asks about background jobs with retries
-  (use pikku-queue) or event-driven triggers (use pikku-trigger).
-installGroups: [core]
----
-
 # Pikku Scheduled Tasks
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Wire Pikku functions to run on a schedule using cron expressions. Uses `pikkuVoidFunc` (no input/output).
-
-`pikku dev`, `pikku serve` and the standalone deploy adapter each register a scheduler service for you, so a wired task runs without any setup. Only register one yourself when deploying somewhere those do not reach, and then take it off the queue factory (`bullFactory.getSchedulerService()`, `pgBossFactory.getSchedulerService()` — see `pikku-queue`) so it survives a restart and is shared between instances.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions and their types
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
 ## API Reference
 
 ### `wireScheduler(config)`
 
 ```typescript
-import { wireScheduler } from '@pikku/core/scheduler'
+import { wireScheduler } from '#pikku/scheduler'
 
 wireScheduler({
   name: string,            // Unique scheduler name

package/skills/{pikku-trigger/SKILL.md → pikku-wiring/references/trigger.md}

@@ -1,38 +1,5 @@
----
-name: pikku-trigger
-description: >-
-  Use when adding event-driven functions that respond to system events like Redis pub/sub,
-  PostgreSQL LISTEN/NOTIFY, or custom event sources. Covers wireTrigger, wireTriggerSource, and
-  pikkuTriggerFunc. TRIGGER when: code uses wireTrigger/wireTriggerSource/pikkuTriggerFunc, user
-  asks about event-driven functions, Redis pub/sub, PostgreSQL LISTEN/NOTIFY, or reacting to
-  external events. DO NOT TRIGGER when: user asks about scheduled tasks (use pikku-schedule) or
-  background job queues (use pikku-queue).
-installGroups: [core]
----
-
 # Pikku Trigger Wiring
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Wire Pikku functions to fire when external events occur. Triggers connect event sources (Redis pub/sub, PostgreSQL LISTEN/NOTIFY, polling, webhooks) to Pikku functions.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions and their types
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
 ## API Reference
 
 All three come from `#pikku`. A trigger is deliberately split in two: the
@@ -172,16 +139,6 @@ wireTriggerSource({
 })
 ```
 
-### Triggers vs Queues
-
-| Feature     | Trigger                            | Queue                          |
-| ----------- | ---------------------------------- | ------------------------------ |
-| Execution   | Synchronous, in-process            | Async, distributed             |
-| Reliability | At-most-once                       | At-least-once (with retries)   |
-| Use case    | React to events immediately        | Reliable background processing |
-| Source      | External systems (Redis, PG, etc.) | Enqueued programmatically      |
-
-Use triggers for real-time reactions. Use queues for reliable, retryable background work.
 
 ## Complete Example
 

package/skills/pikku-workflow/SKILL.md

@@ -5,8 +5,8 @@ description: >-
   Covers pikkuWorkflowFunc, workflow steps (do, sleep, suspend), graph workflows, and HTTP wiring.
   TRIGGER when: code uses pikkuWorkflowFunc/pikkuWorkflowGraph, user asks about workflows,
   multi-step processes, durable execution, suspend/resume, or DAG orchestration. DO NOT TRIGGER
-  when: user asks about simple background jobs (use pikku-queue) or scheduled tasks (use
-  pikku-schedule).
+  when: user asks about simple background jobs (use pikku-wiring) or scheduled tasks (use
+  pikku-wiring).
 installGroups: [core]
 ---
 
@@ -27,6 +27,43 @@ See `pikku-concepts` for the core mental model.
 
 Build durable, multi-step workflows with automatic retry, sleep, suspend/resume, and parallel execution. Steps are cached for replay safety.
 
+## Decide FIRST: should this even BE a workflow?
+
+The deciding question is: **does any part of this cross an external boundary that can fail and MUST NOT be lost or double-run** — a payment authorised/captured through a provider, a third-party API call, an email/webhook, a wait for approval? If yes → workflow (durability, retries, restart-survival, and a visible run). If it's **a single algorithm done in one shot, purely local, and not reused elsewhere** → a plain `pikkuFunc` is correct; do NOT wrap it in a workflow.
+
+- **Checkout WITH payment → workflow.** Get cart → compute total → **(atomic: create order + order items, deduct stock, clear cart)** → **charge payment through the provider** → send confirmation email. It's a workflow because the payment leg (and the email) are external and must be **retried, not lost, and not charged twice** across a restart — and the user benefits from seeing where the run is.
+- **Checkout with NO external payment** — e.g. it just records the order and decrements stock in one transaction, nothing leaves the process — is a **single-shot algorithm**: a plain `pikkuFunc` wrapping one `kysely.transaction`. Not a workflow. A workflow here would add durability machinery for a thing that already commits atomically in one shot.
+- **One durable step is NOT a workflow — it's a queue worker.** A lone side-effect that must be retried / not lost (send one email, fire one webhook, one external charge) → a **queue worker** (`pikku-queue`), enqueued fire-and-forget. A workflow adds a step graph for a thing that has no steps to orchestrate. (A single non-durable step is just a direct RPC call.)
+- Also workflows: onboarding sequences, settlements/payouts, digests and batch sends, anything that waits (`sleep`/`suspend`) or fans out with retries — the common thread is **multiple** steps or a durable wait, never a single step.
+
+**HARD RULE — never a single-RPC (one-step) workflow.** A workflow whose body is one `workflow.do('x', 'someRpc', …)` is a mislabeled durable function, not orchestration. Route by durability, NOT into a workflow:
+
+- **Not durable** — the caller wants the result now / it can just run in-request → **call the RPC directly** (this is also the synchronous path). No workflow, no queue.
+- **Durable** — must be **retried / not lost / survive a restart** (one email, one webhook, one external charge) → a **queue worker** (`wireQueueWorker` + `queueService.add(...)`). Fire-and-forget, retried by the queue.
+
+There is no "one-step workflow is justified for the durability" exception — durability for a single step is a QUEUE. A workflow earns its name only with genuine multi-step orchestration (a `sleep`/`suspend` wait, fan-out, or a saga).
+
+**Atomicity is a TRANSACTION, not a workflow.** All-or-nothing multi-write units (create order + items + deduct stock + clear cart) belong inside ONE `kysely.transaction(async (trx) => { … })` — a single step or a single plain `pikkuFunc` — **never split across workflow steps.** A step is a unit of RETRY and REPLAY, not a unit of atomicity: pikku opens no transaction around `workflow.do`, so a step that does three writes and throws on the third leaves the first two committed, and the retry runs them again. Spreading one logical transaction over several steps is the same failure one level up. Your writes are atomic only where YOU opened a transaction, so open one inside the step (reach for compensating/saga steps only when you truly need cross-service rollback). So a payment checkout is a workflow whose _atomic DB writes are ONE step that opens ONE transaction_, with the payment charge and email as the other durable steps around it.
+
+**A retried step re-runs its side effects.** Replay caching only covers steps that already
+returned; a step that failed — or that timed out after the provider accepted it — runs again
+from the top, so a charge, an email or a webhook can fire twice. Durability is at-least-once,
+not exactly-once. Pass a stable idempotency key the provider deduplicates on, derived from the
+workflow's own data rather than generated inside the step:
+
+```typescript
+await workflow.do('Charge', 'chargePayment', {
+  orderId: data.orderId,
+  amount: data.amount,
+  idempotencyKey: `order-${data.orderId}-charge`,
+})
+```
+
+`randomUUID()` or `Date.now()` inside the step is a different key on every attempt, which is
+the double-charge. Where the provider has no such header, make the step itself idempotent —
+check for the effect before performing it, or record a unique row that the second attempt
+collides with.
+
 ## Choosing the right factory
 
 | Factory                    | When to use                                                                                                                                                                                                | Step-graph view?              |

package/skills/pikku-aws/SKILL.md

@@ -1,161 +0,0 @@
----
-name: pikku-aws
-description: >-
-  Use when setting up AWS services (S3, SQS, Secrets Manager) in a Pikku app. Covers S3Content for
-  file storage, SQSQueueService for queues, and AWSSecrets for secret management. TRIGGER when:
-  code uses S3Content, SQSQueueService, AWSSecrets, or user asks about AWS integration, S3
-  uploads, SQS queues, or AWS Secrets Manager with Pikku. DO NOT TRIGGER when: user asks about AWS
-  Lambda runtime (use pikku-deploy-lambda).
----
-
-# Pikku AWS Services
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-`@pikku/aws-services` provides AWS-backed implementations of Pikku's content, queue, and secret service interfaces.
-
-## Installation
-
-```bash
-yarn add @pikku/aws-services
-```
-
-## API Reference
-
-### `S3Content` (File Storage)
-
-```typescript
-import { S3Content } from '@pikku/aws-services'
-
-const content = new S3Content(
-  config: { bucketName: string; region: string; endpoint?: string },
-  logger: Logger,
-  signConfig: { keyPairId: string; privateKey: string }
-)
-```
-
-`endpoint` is what points the client at LocalStack or an S3-compatible store.
-
-**Methods** — every one takes a single **args object**, matching the shared
-`ContentService` interface. None of them are positional:
-
-- `signURL({ url, dateLessThan, dateGreaterThan? }): Promise<string>` — CloudFront-sign an absolute URL
-- `signContentKey({ bucket, contentKey, dateLessThan, dateGreaterThan? }): Promise<string>`
-- `getUploadURL({ bucket, fileKey, contentType, visibility? }): Promise<{ uploadUrl, assetKey }>` — `visibility` is ignored
-- `readFile({ bucket, key }): Promise<ReadableStream | NodeJS.ReadableStream>`
-- `readFileAsBuffer({ bucket, key }): Promise<Buffer>`
-- `writeFile({ bucket, key, stream }): Promise<boolean>`
-- `copyFile({ bucket, key, fromAbsolutePath }): Promise<boolean>`
-- `deleteFile({ bucket, key }): Promise<boolean>`
-
-### One real bucket, logical buckets as prefixes
-
-The `bucket` on every call is a **logical** bucket stored as a path prefix
-(`${bucket}/${key}`) inside the single S3 bucket named by `bucketName`. Don't
-provision an S3 bucket per logical bucket — the config takes only one.
-
-### Behaviours worth knowing before you rely on them
-
-- **`signURL` fails open.** A signing error is logged and the _unsigned_ URL is
-  returned rather than thrown. If your CloudFront distribution is private the
-  client then gets a 403; if it isn't, you have just handed out an unrestricted
-  link. Check that `signConfig` is a valid CloudFront key pair at boot.
-- **`signContentKey` builds `https://<bucketName>/<bucket>/<contentKey>`** — it
-  uses `bucketName` as the _host_. For signed content the value must therefore be
-  your CloudFront domain, not a plain bucket name, which also means the same
-  config field is doing two jobs.
-- **Presigned upload URLs expire after a fixed 3600s.** It is not configurable
-  through the service.
-- **Write paths swallow failures.** `writeFile`, `copyFile` and `deleteFile` log
-  and return `false` rather than throwing; the read paths throw. Check the
-  boolean.
-
-### `SQSQueueService` (Queue)
-
-```typescript
-import { SQSQueueService } from '@pikku/aws-services'
-
-const queue = new SQSQueueService({
-  region: string,
-  queueUrlPrefix: string, // e.g. 'https://sqs.us-east-1.amazonaws.com/123456789/'
-  endpoint?: string,      // LocalStack or a custom SQS endpoint
-})
-```
-
-Implements `QueueService`. Note: `supportsResults = false` — job status tracking is not supported.
-
-**Methods:**
-
-- `add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>` — Enqueue a message; returns SQS's `MessageId`
-- `getJob()` — always **throws**. SQS is fire-and-forget; reach for BullMQ or PgBoss when you need the result back.
-
-The queue URL is `queueUrlPrefix + queueName`, so the queue name in `wireQueueWorker` has to match the SQS queue exactly.
-
-Constraints inherited from SQS, enforced in `add`:
-
-- `options.delay` is in **milliseconds** and is floored to whole seconds. Over
-  900_000ms (15 minutes) or negative throws before the message is sent.
-- Standard queues only — no FIFO, so no `MessageGroupId` and no ordering
-  guarantee.
-- `data` is `JSON.stringify`d, which is where a `Date` or a `Map` quietly
-  degrades.
-
-### `AWSSecrets` (Secrets Manager)
-
-```typescript
-import { AWSSecrets } from '@pikku/aws-services'
-
-const secrets = new AWSSecrets({ awsRegion: 'eu-west-2' })
-```
-
-`AWSConfig` has one field, `awsRegion` — there is no credentials option; the SDK's
-default provider chain (instance role, env, profile) supplies those.
-
-**Methods:**
-
-- `getSecret<T = string>(SecretId: string): Promise<SecretValue<T>>` — a JSON secret is parsed automatically, so pass a shape as `T` (a non-JSON value comes back as the raw string). The result is a branded `SecretValue`, not a bare value — reveal it where it is used rather than passing it through logs
-- `getSecrets<T>(SecretIds: (keyof T & string)[]): Promise<Partial<T>>` — Batch fetch; missing keys are omitted rather than thrown
-- `hasSecret(SecretId: string): Promise<boolean>` — Check if secret exists
-- `setSecret` / `deleteSecret` — **not implemented** for `AWSSecrets`; it throws. Manage AWS secrets out of band.
-
-Every `getSecret` failure — missing secret, denied permission, a secret holding
-only binary — surfaces as the same `FATAL: Error finding secret: <id>`, with the
-real reason on the error's `cause`. Read `cause` before concluding the secret
-doesn't exist. `hasSecret` performs a full fetch and returns `false` for any
-error, so it can't distinguish "absent" from "not allowed" either.
-
-## Usage Patterns
-
-### S3 Content Service
-
-```typescript
-const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new PinoLogger()
-  const content = new S3Content(
-    { bucketName: config.s3Bucket, region: config.awsRegion },
-    logger,
-    { keyPairId: config.cfKeyPairId, privateKey: config.cfPrivateKey }
-  )
-  return { config, logger, content }
-})
-```
-
-### SQS Queue
-
-```typescript
-const createSingletonServices = pikkuServices(async (config) => {
-  const queue = new SQSQueueService({
-    region: config.awsRegion,
-    queueUrlPrefix: config.sqsUrlPrefix,
-  })
-  return { config, queue }
-})
-```