oblien 2.2.37 → 2.2.38

package/dist/types/cdn.d.ts

@@ -0,0 +1,301 @@
+/** Scope of a CDN access token. */
+export type CdnTokenScope = 'user' | 'admin';
+/** A logged CDN file record (API plane). */
+export interface CdnFile {
+    id: number;
+    user_id: string;
+    /** Namespace slug this file belongs to, or null for unnamespaced files. */
+    namespace?: string | null;
+    filename: string;
+    original_filename?: string | null;
+    original_url?: string | null;
+    file_path: string;
+    cdn_url: string;
+    size: number;
+    mime_type: string;
+    variants: unknown[];
+    metadata: Record<string, unknown>;
+    upload_type: 'upload' | 'url';
+    is_deleted: boolean;
+    deleted_at?: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** A single image-variant spec. Provide at least a width or a height. */
+export interface CdnVariantSpec {
+    width?: number;
+    height?: number;
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+    quality?: number;
+    blur?: number;
+    format?: 'jpeg' | 'png' | 'webp';
+    withoutEnlargement?: boolean;
+}
+/**
+ * Per-request CDN options, carried in the permit `metadata`. The CDN has no
+ * server presets — the client chooses exactly which variants to generate for
+ * this upload. Omit `variantNames` to get the node's default set; pass
+ * `variantNames: []` to skip variants (original only).
+ */
+export interface CdnVariantOptions {
+    /** Variant names to generate for this upload. */
+    variantNames?: string[];
+    /** Per-variant specs keyed by name (usually the same names as `variantNames`). */
+    customVariants?: Record<string, CdnVariantSpec>;
+    /** Keep the uploaded original (default true). */
+    keepOriginal?: boolean;
+    /** Which produced variant becomes the top-level `url` (default 'full'). */
+    primary?: string;
+    /** Re-encode a large original in place. */
+    optimizeOriginal?: {
+        maxBytes?: number;
+        quality?: number;
+        format?: 'jpeg' | 'png' | 'webp';
+    };
+    /** Auto-delete this upload after N seconds (node-owned TTL). */
+    ttl?: number;
+    /** Auto-delete at this epoch time (seconds or ms). */
+    expireAt?: number;
+    /** Lower the per-file byte cap for this upload (can only lower it). */
+    maxBytes?: number;
+    /** Any additional opaque metadata the API stores and echoes back. */
+    [key: string]: unknown;
+}
+export interface CdnTokenParams {
+    /**
+     * Namespace slug to bind the token (and the uploads it authorizes) to.
+     * Namespace-scoped API keys are always forced to their own namespace;
+     * admin keys may target any namespace or omit it.
+     */
+    namespace?: string;
+    /**
+     * CDN processing directives (variant plan + TTL/maxBytes) — issued into the
+     * permit by the API at mint time and read by the edge from there, never sent
+     * on the upload request. See {@link CdnVariantOptions}.
+     */
+    variants?: CdnVariantOptions;
+    /**
+     * Opaque customer metadata: stored with each file and echoed back, never
+     * interpreted for processing. (Variant directives go in `variants`.)
+     */
+    metadata?: Record<string, unknown>;
+}
+export interface CdnTokenResponse {
+    success: boolean;
+    /** Short-lived (1 minute) CDN JWT — pass as `Bearer <token>` to the edge. */
+    token: string;
+    scope: CdnTokenScope;
+    permissions: string[];
+    /** Namespace the token is bound to, or null. */
+    namespace: string | null;
+    expiresIn: string;
+    message?: string;
+}
+/** A file to upload: its bytes plus a filename and optional content type. */
+export interface CdnUploadInput {
+    data: Blob | Buffer | Uint8Array | ArrayBuffer;
+    filename: string;
+    /** MIME type — defaults to `application/octet-stream` if omitted. */
+    contentType?: string;
+}
+export interface CdnUploadParams {
+    /** Namespace to attribute the upload to (used to mint the token). */
+    namespace?: string;
+    /**
+     * Reuse a CDN token you already minted (e.g. via {@link CdnTokenResponse}).
+     * When omitted, `upload` mints a fresh user token automatically.
+     */
+    token?: string;
+    /**
+     * CDN processing directives (variant plan + TTL/maxBytes) for this upload.
+     * Applied only when a token is auto-minted — ignored if you pass your own
+     * `token` (bake them in at mint time instead). See {@link CdnVariantOptions}.
+     */
+    variants?: CdnVariantOptions;
+    /** Opaque customer metadata (stored + echoed, never interpreted). */
+    metadata?: Record<string, unknown>;
+}
+export interface CdnUploadVariant {
+    variant: string;
+    url: string;
+}
+export interface CdnUploadResponse {
+    success: boolean;
+    /** The node's uuid for this file (also the API record's node_file_id). */
+    file_id: string;
+    url: string;
+    filename: string;
+    size: number;
+    mime: string;
+    variants: CdnUploadVariant[];
+    /** Whether the record was durably queued to the API for recording. */
+    recorded: boolean;
+    /** Present when the upload has a TTL. */
+    expires_at?: string | number;
+}
+export interface CdnUploadManyResponse {
+    success: boolean;
+    files: Array<{
+        file_id: string;
+        originalFilename?: string;
+        url: string;
+        filename: string;
+        size: number;
+        mime: string;
+        variants: CdnUploadVariant[];
+        expires_at?: string | number;
+    }>;
+    invalidFiles?: Array<{
+        originalFilename: string;
+        error: string;
+    }>;
+    totalCount: number;
+    recorded: boolean;
+}
+export interface CdnProcessUrlsParams {
+    urls: string[];
+    maxBatch?: number;
+    concurrency?: number;
+    /** Namespace to attribute the processed files to. */
+    namespace?: string;
+    /** Reuse a minted CDN token instead of auto-minting one. */
+    token?: string;
+    /**
+     * CDN processing directives (baked into the minted token). Applied only when
+     * a token is auto-minted. See {@link CdnVariantOptions}.
+     */
+    variants?: CdnVariantOptions;
+    /** Opaque customer metadata (stored + echoed, never interpreted). */
+    metadata?: Record<string, unknown>;
+}
+export interface CdnProcessUrlsResponse {
+    success: boolean;
+    files: Array<{
+        file_id: string;
+        originalUrl?: string;
+        url: string;
+        filename: string;
+        size: number;
+        mime: string;
+        variants: CdnUploadVariant[];
+        expires_at?: string | number;
+    }>;
+    errors?: Array<{
+        url: string;
+        error: string;
+        index?: number;
+    }>;
+    totalProcessed: number;
+    totalErrors: number;
+    recorded: boolean;
+}
+export interface CdnLimitsResponse {
+    limits: Record<string, number>;
+    totalLimit: number;
+    maxFiles: number;
+}
+export interface CdnVariantOptionsResponse {
+    success: boolean;
+    /** The variant set applied when a request specifies none. */
+    defaultVariants: Record<string, unknown>;
+    /** Schema for the per-request `customVariants` a client may send. */
+    customVariantSchema: Record<string, unknown>;
+}
+export interface CdnListParams {
+    page?: number;
+    limit?: number;
+    /** Filter to a single namespace (namespace keys are pinned to their own). */
+    namespace?: string;
+    include_deleted?: boolean;
+    upload_type?: 'upload' | 'url';
+    sort_by?: 'created_at' | 'size' | 'filename';
+    sort_order?: 'ASC' | 'DESC';
+}
+export interface CdnPagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+export interface CdnListResponse {
+    success: boolean;
+    data: {
+        files: CdnFile[];
+        pagination: CdnPagination;
+    };
+}
+export interface CdnStatsParams {
+    /** Restrict the stats to a single namespace. */
+    namespace?: string;
+}
+export interface CdnStats {
+    totalFiles: number;
+    totalSize: number;
+    activeFiles: number;
+    activeSize: number;
+    uploadedFiles: number;
+    urlFiles: number;
+}
+export interface CdnStatsResponse {
+    success: boolean;
+    data: CdnStats;
+}
+export interface CdnUsageParams {
+    /** Restrict to a single namespace (namespace keys are pinned to their own). */
+    namespace?: string;
+    /** Month to report ingest for, 'YYYY-MM'. Defaults to the current month. */
+    period?: string;
+}
+export interface CdnUsageResponse {
+    success: boolean;
+    data: {
+        namespace: string | null;
+        period: string;
+        /** Bytes/files UPLOADED in the month (counts even if later deleted). */
+        ingest: {
+            bytes: number;
+            files: number;
+        };
+        /** Current live footprint (original + variants). */
+        active: {
+            bytes: number;
+            files: number;
+        };
+        /** Configured caps (present when scoped to one namespace). */
+        limits?: {
+            cdn_max_bytes: number | null;
+            cdn_monthly_bytes: number | null;
+        };
+    };
+}
+export interface CdnUsageSeriesParams {
+    namespace?: string;
+    /** Bucket size. Default 'day'. */
+    interval?: 'day' | 'month';
+    /** Number of days back (interval 'day', default 30, max 366). */
+    days?: number;
+    /** Number of months back (interval 'month', default 12, max 120). */
+    months?: number;
+}
+export interface CdnUsageSeriesResponse {
+    success: boolean;
+    data: {
+        namespace: string | null;
+        interval: 'day' | 'month';
+        from: string;
+        to: string;
+        /** Zero-filled ingest per bucket, oldest → newest. */
+        series: Array<{
+            bucket: string;
+            bytes: number;
+            files: number;
+        }>;
+    };
+}
+export interface CdnFileResponse {
+    success: boolean;
+    data: CdnFile;
+    error?: string;
+}
+//# sourceMappingURL=cdn.d.ts.map

package/dist/types/cdn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdn.d.ts","sourceRoot":"","sources":["../../src/types/cdn.ts"],"names":[],"mappings":"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"}

package/dist/types/cdn.js

@@ -0,0 +1,10 @@
+// ── CDN ──────────────────────────────────────────────────────────────
+//
+// The CDN has two planes:
+//   • API plane  (api.oblien.com/cdn/*)  — mint tokens, list/stat/manage files
+//   • Edge plane (cdn.oblien.com/api/*)  — upload files with a minted token
+//
+// Every params interface accepts an optional `namespace` so uploads and
+// listings can be scoped to a namespace, mirroring the rest of the SDK.
+export {};
+//# sourceMappingURL=cdn.js.map

package/dist/types/cdn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdn.js","sourceRoot":"","sources":["../../src/types/cdn.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,EAAE;AACF,0BAA0B;AAC1B,+EAA+E;AAC/E,4EAA4E;AAC5E,EAAE;AACF,wEAAwE;AACxE,wEAAwE"}

package/dist/types/client.d.ts

@@ -4,10 +4,20 @@ export interface OblienApiKeyOptions {
     clientSecret: string;
     /** @default 'https://api.oblien.com' */
     baseUrl?: string;
+    /**
+     * CDN edge base URL (including the `/api` mount) that uploads are sent to.
+     * @default 'https://cdn.oblien.com/api'
+     */
+    cdnBaseUrl?: string;
 }
 export interface OblienTokenOptions {
     token: string;
     /** @default 'https://api.oblien.com' */
     baseUrl?: string;
+    /**
+     * CDN edge base URL (including the `/api` mount) that uploads are sent to.
+     * @default 'https://cdn.oblien.com/api'
+     */
+    cdnBaseUrl?: string;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/types/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/types/client.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AAErE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/types/client.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AAErE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/types/index.d.ts

@@ -13,4 +13,5 @@ export type { TokenScope, TokenCreateParams, TokenCreateResponse, } from './toke
 export type { PushPlatform, PushDeviceStatus, PushTokenStatus, PushDevice, RegisterDeviceParams, PushDeviceListResponse, WorkspacePushToken, CreatedWorkspacePushToken, CreatePushTokenParams, PushTokenListResponse, SendNotificationParams, SendNotificationResponse, } from './notifications.js';
 export type { WebhookEvent, Webhook, WebhookCreateParams, WebhookUpdateParams, WebhookListParams, WebhookListResponse, WebhookEventsResponse, } from './webhooks.js';
 export type { AnalyticsOverview, AnalyticsDomainSummary, AnalyticsHomeSummary, AnalyticsBucket, AnalyticsTimeseriesParams, AnalyticsTimeseriesResponse, AnalyticsGeoEntry, AnalyticsGeoParams, AnalyticsGeoResponse, AnalyticsRequestEntry, AnalyticsRequestsParams, AnalyticsRequestsResponse, AnalyticsStreamTokenResponse, } from './analytics.js';
+export type { CdnTokenScope, CdnFile, CdnTokenParams, CdnTokenResponse, CdnUploadInput, CdnUploadParams, CdnUploadVariant, CdnUploadResponse, CdnUploadManyResponse, CdnProcessUrlsParams, CdnProcessUrlsResponse, CdnLimitsResponse, CdnVariantOptionsResponse, CdnListParams, CdnPagination, CdnListResponse, CdnStatsParams, CdnStats, CdnStatsResponse, CdnFileResponse, } from './cdn.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/docs/cdn.md

@@ -0,0 +1,119 @@
+# CDN
+
+Upload files to the Oblien CDN and manage what you've stored. The CDN spans two planes: the **API plane** (`api.oblien.com/cdn/*`) mints short-lived tokens and lists/manages logged files, and the **edge plane** (`cdn.oblien.com`) receives the actual uploads. `client.cdn.upload()` handles both — it mints a token and posts the file for you.
+
+Everything is **namespace-aware**: pass `namespace` to scope a token, upload, or listing. Namespace-scoped API keys are automatically pinned to their own namespace by the server; admin keys may target any namespace or omit it (seeing all of their files).
+
+```typescript
+import { readFileSync } from 'node:fs';
+
+// One-shot upload (mints a namespace-bound token, then uploads to the edge)
+const { url } = await client.cdn.upload(
+  { data: readFileSync('./logo.png'), filename: 'logo.png', contentType: 'image/png' },
+  { namespace: 'tenant-a' },
+);
+
+// Choose exactly which variants to generate for THIS upload (no presets).
+// `variants` are API-issued into the token; `metadata` is opaque customer data.
+const res = await client.cdn.upload(
+  { data: readFileSync('./avatar.png'), filename: 'avatar.png', contentType: 'image/png' },
+  {
+    namespace: 'tenant-a',
+    variants: {
+      variantNames: ['large', 'small'],
+      customVariants: {
+        large: { width: 400, height: 400, fit: 'cover', quality: 90, format: 'jpeg' },
+        small: { width: 50, height: 50, fit: 'cover' },
+      },
+      keepOriginal: false,
+      primary: 'large',
+      ttl: 3600, // auto-delete after 1h (optional)
+    },
+    metadata: { userId: 'u_123', purpose: 'avatar' }, // opaque, echoed back
+  },
+);
+// res.variants → [{ variant: 'large', url }, { variant: 'small', url }]
+
+// Mint a token yourself (e.g. to hand to a browser uploader) — the variants are
+// baked into the permit at mint time, since the edge reads them from there
+const { token } = await client.cdn.token({
+  namespace: 'tenant-a',
+  variants: { variantNames: ['thumb'], customVariants: { thumb: { width: 150, height: 150 } } },
+});
+
+// List / stats, scoped to a namespace
+const { data } = await client.cdn.list({ namespace: 'tenant-a', limit: 20 });
+await client.cdn.stats({ namespace: 'tenant-a' });
+
+// Manage a single file
+await client.cdn.get(fileId);
+await client.cdn.delete(fileId);   // soft delete
+await client.cdn.restore(fileId);
+```
+
+## Methods
+
+| Method | Plane | Description |
+| --- | --- | --- |
+| `cdn.token({ namespace?, variants?, metadata? })` | API | Mint a USER-scope token (upload + process), valid 1 minute |
+| `cdn.adminToken({ namespace?, variants?, metadata? })` | API | Mint an ADMIN-scope token (full edge access; admin keys only) |
+| `cdn.upload(file, { namespace?, token?, variants?, metadata? })` | edge | Upload one file (auto-mints a token unless one is passed) |
+| `cdn.uploadMany(files, { namespace?, token?, variants?, metadata? })` | edge | Upload several files in one request |
+| `cdn.processUrls({ urls, namespace?, variants?, metadata?, … })` | edge | Ingest and process files from remote URLs |
+| `cdn.getLimits()` / `cdn.getVariantOptions()` | edge | Edge upload limits / default variants + custom-variant schema |
+| `cdn.list({ namespace?, … })` | API | List logged files with pagination |
+| `cdn.stats({ namespace? })` | API | All-time storage statistics |
+| `cdn.usage({ namespace?, period? })` | API | Month usage (ingest + active) + caps |
+| `cdn.usageSeries({ namespace?, interval?, days?, months? })` | API | Windowed ingest series for charts |
+| `cdn.get(fileId)` | API | Fetch a single logged file |
+| `cdn.delete(fileId)` / `cdn.restore(fileId)` | API | Soft-delete / restore a file |
+
+A `file` is `{ data, filename, contentType? }` where `data` is a `Blob`, `Buffer`, `Uint8Array`, or `ArrayBuffer`.
+
+## Variants (API-issued, per request)
+
+There are **no server-side presets**. Each upload decides exactly which variants
+to generate via the dedicated **`variants`** field on the token/upload call
+(distinct from opaque `metadata`). Options (all optional):
+
+| Field | Meaning |
+| --- | --- |
+| `variantNames: string[]` | Which variants to produce. Omit → the node's default set; `[]` → original only. |
+| `customVariants: { [name]: spec }` | Per-variant `spec`: `{ width?, height?, fit?, quality?, blur?, format?, withoutEnlargement? }` (provide width and/or height). |
+| `keepOriginal: boolean` | Keep the uploaded original (default `true`). |
+| `primary: string` | Which produced variant is the top-level `url` (default `'full'`). |
+| `optimizeOriginal: { maxBytes?, quality?, format? }` | Re-encode a large original in place. |
+| `ttl: number` / `expireAt: number` | Auto-delete after N seconds / at an epoch time (the node deletes it and reports back). |
+| `maxBytes: number` | Lower the per-file size cap for this upload. |
+
+`variants` is baked into the short-lived token at mint time (the edge reads it
+from the permit), so it applies whether you call `upload()` directly or mint a
+token yourself and hand it to a browser. When you pass your own `token`, set the
+options at the time you minted it — `upload({ token })` ignores `variants`.
+
+`metadata` is separate: opaque customer key/values the API stores with each file
+and echoes back, never interpreted for processing.
+
+`cdn.getVariantOptions()` returns the current `defaultVariants` set and the
+`customVariantSchema` (field bounds) for discovery.
+
+## Configuration
+
+Uploads target `https://cdn.oblien.com/api` by default. Override it (e.g. for local development against the CDN service directly) with `cdnBaseUrl`:
+
+```typescript
+const client = new Oblien({ clientId, clientSecret, cdnBaseUrl: 'http://localhost:3240' });
+```
+
+## CLI
+
+```bash
+oblien cdn upload ./logo.png --namespace tenant-a
+oblien cdn upload ./logo.png --namespace tenant-a --names thumb,medium
+oblien cdn upload ./a.png --variants '{"variantNames":["sq"],"customVariants":{"sq":{"width":200,"height":200}}}'
+oblien cdn upload ./tmp.png --ttl 3600 --meta '{"orderId":"abc123"}'   # ttl + opaque metadata
+oblien cdn list --namespace tenant-a --json
+oblien cdn stats --namespace tenant-a
+oblien cdn token --namespace tenant-a --names thumb
+oblien cdn delete 42
+```

package/docs/runtime.md

@@ -21,6 +21,7 @@ This enables the Runtime API server (if needed), fetches a gateway JWT, and retu
 | `rt.search` | Content search (ripgrep) + filename search |
 | `rt.watcher` | Watch directories for real-time file-change events |
 | `rt.ws()` | WebSocket — persistent connection for terminal I/O and watcher events |
+| `rt.proxy(port)` | Reverse-proxy HTTP/WebSocket to a **loopback** service inside the workspace |
 
 ## Files
 
@@ -50,4 +51,33 @@ const matches = await rt.search.content({ query: 'handleRequest', path: '/app' }
 const files = await rt.search.files({ query: 'controller' });
 ```
 
+## Proxy
+
+Reach an HTTP or WebSocket server running on a **loopback port inside the workspace** (e.g. a dev server on `127.0.0.1:3000`) as if you were talking to it directly. Headers, streaming/SSE, and WebSocket upgrades pass through near-natively. For safety the proxy is **loopback-only** — it cannot reach the VM's private network or the internet.
+
+```typescript
+// HTTP — returns a raw fetch Response (status, headers, body/stream)
+const res = await rt.proxy(3000).fetch('/api/users?limit=10');
+const users = await res.json();
+
+// POST with a body
+await rt.proxy(3000).fetch('/api/users', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ name: 'ada' }),
+});
+
+// Streaming (SSE) passes through untouched
+const stream = await rt.proxy(8080).fetch('/events');
+for await (const chunk of stream.body!) { /* handle chunk */ }
+
+// WebSocket
+const ws = rt.proxy(3000).ws('/socket');
+ws.onmessage = (e) => console.log(e.data);
+```
+
+The runtime connection token is attached automatically (via the `Authorization` header for HTTP, and the `token` query param for WebSocket) and is **stripped before the request reaches the in-VM app**, so it never leaks to your code running inside the workspace.
+
+**HTTP transport (advanced).** The SDK calls the runtime endpoint `GET|POST|… /proxy<path>` and selects the target with the `X-Oblien-Proxy-Target: <port>` header. Equivalent forms the runtime also accepts: the `x_oblien_target=<port>` query param (used for WebSocket, since browsers can't set headers), or the path form `/proxy/<port>/<path>`. `token` and `x_oblien_target` are reserved query params and are removed before forwarding.
+
 **Full reference:** [Runtime API docs](https://oblien.com/docs/runtime-api)

package/docs/serve.md

@@ -0,0 +1,84 @@
+# Static server
+
+Serve a folder over HTTP and put it on the public internet in one step. The
+server is built entirely on Node's `http`/`fs` — **no extra dependencies** — and
+the CLI wires it straight into the [edge tunnel](./edge-tunnel.md), so a
+directory becomes a public HTTPS URL with a single command.
+
+## CLI
+
+```bash
+oblien serve                       # serve ./public
+oblien serve ./dist                # serve ./dist
+oblien serve ./dist --slug my-app  # pick the public subdomain
+oblien serve ./build --spa         # single-page-app fallback
+oblien serve ./site --domain preview.example.com
+```
+
+`oblien serve` starts a static server on a loopback port and then forwards it
+through the edge exactly like `oblien tunnel <port>` — so every tunnel flag
+works here too:
+
+| Flag | Description |
+| --- | --- |
+| `--port <n>` | Local port to serve on (default: an OS-assigned free port) |
+| `--slug <slug>` | Custom subdomain slug for the public URL |
+| `--name <name>` | Tunnel display name (default: the folder name) |
+| `--domain <domain>` | Base domain or exact custom hostname (see [edge-tunnel](./edge-tunnel.md)) |
+| `--expires-in <ttl>` | Tunnel token TTL, e.g. `30s`, `5m`, `1h`, `7d` |
+| `--spa` | Serve `index.html` for any unmatched path (client-side routing) |
+| `--no-listing` | Disable auto-generated directory listings |
+| `--index <file>` | Directory index filename (default: `index.html`) |
+
+Press `Ctrl+C` to stop — the tunnel disconnects and the local server shuts down.
+
+## What the server handles
+
+- **Correct MIME types** for common web, font, image, media, and document extensions.
+- **Streamed responses** (`createReadStream`) — large files never buffer in memory.
+- **`Range` requests** — media seeking / resumable downloads return `206 Partial Content`.
+- **Revalidation** — `ETag` + `Last-Modified` yield `304 Not Modified` on conditional requests.
+- **Directory handling** — serves `index.html`, redirects `/dir` → `/dir/`, and renders a clean listing when there's no index (unless `--no-listing`).
+- **SPA fallback** (`--spa`) — unmatched paths return the root `index.html`.
+- **Path-traversal protection** — requests are resolved against the root; anything escaping it lexically is rejected (`403`), and a file whose canonical path (following symlinks) leaves the root is rejected (`404`).
+- **Dotfiles denied by default** — `.git/`, `.env`, and other dot-paths return `404` (the server is often public), except `.well-known/`. Opt in with `allowDotfiles`.
+
+## Programmatic use
+
+The same server is exported from the SDK, so you can start it yourself and pair
+it with the [`TunnelClient`](./edge-tunnel.md) or use it standalone:
+
+```typescript
+import { startStaticServer } from 'oblien';
+
+const site = await startStaticServer({
+  root: './public',
+  spa: true,           // optional: index.html fallback
+  // port: 8080,       // optional: default is an OS-assigned free port
+  // host: '127.0.0.1' // optional: default loopback only
+});
+
+console.log(`serving on ${site.url}`); // http://127.0.0.1:<port>
+
+// ...later
+await site.close();
+```
+
+`startStaticServer(options)` resolves once the server is listening and returns a
+handle: `{ port, host, url, server, close() }`. The `port` is always resolved —
+even when you omit it and let the OS choose. For finer control, `createStaticServer(options)`
+returns a non-listening `http.Server`, and `createStaticHandler(options)` returns a
+raw `(req, res)` handler you can mount on your own server.
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `root` | `string` | — | Directory to serve (resolved against cwd) |
+| `host` | `string` | `127.0.0.1` | Interface to bind |
+| `port` | `number` | `0` (auto) | Port to listen on |
+| `index` | `string` | `index.html` | Directory index filename |
+| `listing` | `boolean` | `true` | Render a listing when a directory has no index |
+| `spa` | `boolean` | `false` | Serve the root index for unmatched paths |
+| `allowDotfiles` | `boolean` | `false` | Serve dotfiles/dot-directories (`.well-known/` is always allowed) |
+| `onRequest` | `(info) => void` | — | Per-request hook: `{ method, path, status }` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oblien",
-  "version": "2.2.37",
+  "version": "2.2.38",
   "description": "Official TypeScript SDK for the Oblien Workspace API",
   "type": "module",
   "main": "./dist/index.js",