pockethook-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PocketHook
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+# pockethook-sdk
+
+SDK for building [PocketHook](https://pockethook.app)-compatible server responses. Parse incoming requests from the PocketHook iOS app and build properly formatted responses — including text messages, iOS Shortcut triggers, data payloads, and URLs.
+
+## Install
+
+```bash
+bun add pockethook-sdk
+```
+
+```bash
+npm install pockethook-sdk
+```
+
+## Quick Start
+
+```ts
+import { parseRequest, text, toResponse } from "pockethook-sdk";
+
+Bun.serve({
+  port: 3000,
+  async fetch(req) {
+    const { sessionId, chatInput } = parseRequest(await req.json());
+    return toResponse(text(`Echo: ${chatInput}`));
+  },
+});
+```
+
+## API
+
+### Response Builders
+
+#### `text(msg)`
+
+Build a simple text response.
+
+```ts
+import { text } from "pockethook-sdk";
+
+text("Hello from the server!");
+// => [{ msg: "Hello from the server!" }]
+```
+
+#### `shortcut(msg, name, data?)`
+
+Build a response that triggers an iOS Shortcut.
+
+```ts
+import { shortcut } from "pockethook-sdk";
+
+shortcut("Starting backup...", "BackupPhotos", { destination: "icloud" });
+// => [{ msg: "Starting backup...", shortcut: "BackupPhotos", data: { destination: "icloud" } }]
+```
+
+#### `response(options)`
+
+Build a single response with full control over all fields.
+
+```ts
+import { response } from "pockethook-sdk";
+
+response({
+  msg: "File ready",
+  shortcut: "OpenFile",
+  data: { path: "/documents/report.pdf" },
+  url: "https://example.com/report.pdf",
+});
+```
+
+#### `responses(items)`
+
+Build multiple responses for sequential Shortcut execution. PocketHook runs them in order, passing results between Shortcuts.
+
+```ts
+import { responses } from "pockethook-sdk";
+
+responses([
+  { msg: "Downloading...", shortcut: "DownloadFile", data: { id: 42 } },
+  { msg: "Processing...", shortcut: "ConvertToPDF" },
+  { msg: "Done!", shortcut: "ShareFile" },
+]);
+```
+
+### Serialization
+
+#### `toJSON(items)`
+
+Serialize responses to a JSON string.
+
+```ts
+import { response, toJSON } from "pockethook-sdk";
+
+const json = toJSON([response({ msg: "Hello" })]);
+// => '[{"msg":"Hello"}]'
+```
+
+#### `toResponse(items, status?)`
+
+Create a `Response` object with `Content-Type: application/json`. Ready to return from any server handler.
+
+```ts
+import { text, toResponse } from "pockethook-sdk";
+
+toResponse(text("Hello"));
+// => Response { status: 200, headers: { "Content-Type": "application/json" } }
+
+toResponse(text("Created"), 201);
+// => Response { status: 201, ... }
+```
+
+### Request Parsing
+
+#### `parseRequest(body)`
+
+Parse and validate an incoming PocketHook request. Accepts a JSON string, `Uint8Array`, or already-parsed object.
+
+```ts
+import { parseRequest } from "pockethook-sdk";
+
+const { sessionId, chatInput } = parseRequest(await req.json());
+```
+
+Validates:
+- `sessionId` is a valid UUID
+- `chatInput` is a non-empty string (max 10,000 characters)
+
+#### `extractBearerToken(header)`
+
+Extract the token from an `Authorization: Bearer <token>` header.
+
+```ts
+import { extractBearerToken } from "pockethook-sdk";
+
+const token = extractBearerToken(req.headers.get("Authorization"));
+if (token !== process.env.AUTH_TOKEN) {
+  return new Response("Unauthorized", { status: 401 });
+}
+```
+
+#### `validateHttpsUrl(url)`
+
+Validate that a URL uses HTTPS. PocketHook rejects non-HTTPS URLs.
+
+```ts
+import { validateHttpsUrl } from "pockethook-sdk";
+
+validateHttpsUrl("https://example.com"); // => "https://example.com"
+validateHttpsUrl("http://example.com"); // throws Error
+```
+
+## Protocol Reference
+
+### Request Format
+
+PocketHook sends a POST request with a JSON array:
+
+```json
+[
+  {
+    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
+    "action": "sendMessage",
+    "chatInput": "Hello server"
+  }
+]
+```
+
+**Headers:**
+- `Content-Type: application/json`
+- `Authorization: Bearer <token>`
+
+### Response Format
+
+The server must return a JSON array of response objects:
+
+```json
+[
+  {
+    "msg": "Message to display in chat",
+    "shortcut": "ShortcutName",
+    "data": { "key": "value" },
+    "url": "https://example.com"
+  }
+]
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `msg` | string | Yes | Message displayed in the PocketHook chat |
+| `shortcut` | string | No | Name of the iOS Shortcut to trigger |
+| `data` | object | No | Arbitrary data passed to the Shortcut |
+| `url` | string | No | HTTPS URL associated with the response |
+
+**Multiple actions:** Return multiple objects in the array. PocketHook executes shortcuts sequentially, in order.
+
+## Example: Full Server
+
+```ts
+import { parseRequest, extractBearerToken, text, shortcut, responses, toResponse } from "pockethook-sdk";
+
+const AUTH_TOKEN = process.env.AUTH_TOKEN!;
+
+Bun.serve({
+  port: 3000,
+  async fetch(req) {
+    // Authenticate
+    const token = extractBearerToken(req.headers.get("Authorization"));
+    if (token !== AUTH_TOKEN) {
+      return new Response("Unauthorized", { status: 401 });
+    }
+
+    // Parse request
+    const { sessionId, chatInput } = parseRequest(await req.json());
+    const command = chatInput.toLowerCase().trim();
+
+    // Route commands
+    if (command === "backup") {
+      return toResponse(
+        shortcut("Starting backup...", "BackupPhotos", { date: new Date().toISOString() })
+      );
+    }
+
+    if (command === "deploy") {
+      return toResponse(
+        responses([
+          { msg: "Running tests...", shortcut: "RunTests" },
+          { msg: "Building...", shortcut: "BuildProject" },
+          { msg: "Deployed!", shortcut: "NotifyTeam", data: { channel: "general" } },
+        ])
+      );
+    }
+
+    return toResponse(text(`You said: ${chatInput}`));
+  },
+});
+```
+
+## TypeScript Types
+
+All types are exported for use in your own code:
+
+```ts
+import type {
+  PocketHookRequest,
+  PocketHookResponse,
+  ResponseOptions,
+  ParsedRequest,
+} from "pockethook-sdk";
+```
+
+## Requirements
+
+- Bun >= 1.0 or Node.js >= 18
+- TypeScript >= 5 (optional, for type checking)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { PocketHookRequest, PocketHookResponse, PocketHookWrappedResponse, ResponseOptions, ParsedRequest, } from "./types.js";
+export { response, responses, text, shortcut, toJSON, toResponse, } from "./response.js";
+export { parseRequest, validateHttpsUrl, extractBearerToken, } from "./validation.js";

package/dist/index.js

@@ -0,0 +1,110 @@
+// src/validation.ts
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function parseRequest(body) {
+  let parsed;
+  if (typeof body === "string") {
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      throw new Error("Invalid JSON in request body");
+    }
+  } else if (body instanceof ArrayBuffer || body instanceof Uint8Array) {
+    try {
+      const text = new TextDecoder().decode(body);
+      parsed = JSON.parse(text);
+    } catch {
+      throw new Error("Invalid JSON in request body");
+    }
+  } else {
+    parsed = body;
+  }
+  const arr = Array.isArray(parsed) ? parsed : [parsed];
+  const item = arr[0];
+  if (!item || typeof item !== "object") {
+    throw new Error("Request must contain at least one object");
+  }
+  const obj = item;
+  const sessionId = obj.sessionId;
+  if (typeof sessionId !== "string" || !UUID_REGEX.test(sessionId)) {
+    throw new Error("sessionId must be a valid UUID");
+  }
+  const chatInput = obj.chatInput;
+  if (typeof chatInput !== "string" || chatInput.length === 0) {
+    throw new Error("chatInput must be a non-empty string");
+  }
+  if (chatInput.length > 1e4) {
+    throw new Error("chatInput exceeds 10,000 character limit");
+  }
+  return { sessionId, chatInput };
+}
+function validateHttpsUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(`URL must be HTTPS, got: ${parsed.protocol}`);
+  }
+  return url;
+}
+function extractBearerToken(header) {
+  if (!header)
+    return null;
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  return match?.[1] ?? null;
+}
+
+// src/response.ts
+function response(options) {
+  if (!options.msg && options.msg !== "") {
+    throw new Error("msg is required");
+  }
+  const res = { msg: options.msg };
+  if (options.shortcut !== undefined) {
+    if (typeof options.shortcut !== "string" || options.shortcut.length === 0) {
+      throw new Error("shortcut must be a non-empty string");
+    }
+    res.shortcut = options.shortcut;
+  }
+  if (options.data !== undefined) {
+    res.data = options.data;
+  }
+  if (options.url !== undefined) {
+    res.url = validateHttpsUrl(options.url);
+  }
+  return res;
+}
+function responses(items) {
+  if (items.length === 0) {
+    throw new Error("At least one response is required");
+  }
+  return items.map(response);
+}
+function text(msg) {
+  return [response({ msg })];
+}
+function shortcut(msg, name, data) {
+  return [response({ msg, shortcut: name, data })];
+}
+function toJSON(items) {
+  return JSON.stringify(items);
+}
+function toResponse(items, status = 200) {
+  return new Response(toJSON(items), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+export {
+  validateHttpsUrl,
+  toResponse,
+  toJSON,
+  text,
+  shortcut,
+  responses,
+  response,
+  parseRequest,
+  extractBearerToken
+};

package/dist/response.d.ts

@@ -0,0 +1,57 @@
+import type { PocketHookResponse, ResponseOptions } from "./types.js";
+/**
+ * Build a single PocketHook response.
+ *
+ * @example
+ * ```ts
+ * response({ msg: "Hello!" })
+ * // => { msg: "Hello!" }
+ *
+ * response({ msg: "Done", shortcut: "BackupPhotos", data: { count: 42 } })
+ * // => { msg: "Done", shortcut: "BackupPhotos", data: { count: 42 } }
+ * ```
+ */
+export declare function response(options: ResponseOptions): PocketHookResponse;
+/**
+ * Build an array of PocketHook responses (multi-action).
+ * PocketHook executes shortcuts sequentially in order.
+ *
+ * @example
+ * ```ts
+ * responses([
+ *   { msg: "Starting backup...", shortcut: "BackupPhotos" },
+ *   { msg: "Uploading...", shortcut: "UploadToCloud", data: { dest: "s3" } }
+ * ])
+ * ```
+ */
+export declare function responses(items: ResponseOptions[]): PocketHookResponse[];
+/**
+ * Build a simple text-only response.
+ *
+ * @example
+ * ```ts
+ * text("Hello from the server!")
+ * // => [{ msg: "Hello from the server!" }]
+ * ```
+ */
+export declare function text(msg: string): PocketHookResponse[];
+/**
+ * Build a response that triggers a Shortcut.
+ *
+ * @example
+ * ```ts
+ * shortcut("Play Music", "PlaySpotify", { playlist: "chill" })
+ * // => [{ msg: "Play Music", shortcut: "PlaySpotify", data: { playlist: "chill" } }]
+ * ```
+ */
+export declare function shortcut(msg: string, name: string, data?: Record<string, unknown>): PocketHookResponse[];
+/**
+ * Serialize responses to a JSON string ready to send.
+ * Returns the standard PocketHook array format.
+ */
+export declare function toJSON(items: PocketHookResponse[]): string;
+/**
+ * Create a Response object ready to return from a server handler.
+ * Sets Content-Type to application/json.
+ */
+export declare function toResponse(items: PocketHookResponse[], status?: number): Response;

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * PocketHook standard request format.
+ * Sent as a JSON array: [PocketHookRequest]
+ */
+export interface PocketHookRequest {
+    sessionId: string;
+    action: "sendMessage";
+    chatInput: string;
+}
+/**
+ * A single response action from the server.
+ * The server returns an array of these: PocketHookResponse[]
+ */
+export interface PocketHookResponse {
+    /** Message to display in the chat. Required. */
+    msg: string;
+    /** iOS Shortcut name to trigger. Optional. */
+    shortcut?: string;
+    /** Arbitrary data payload passed to the Shortcut. Optional. */
+    data?: Record<string, unknown>;
+    /** HTTPS URL to associate with the response. Optional. Must be HTTPS. */
+    url?: string;
+}
+/**
+ * Server response wrapped in an "output" array.
+ * Alternative format: [{ output: [PocketHookResponse] }]
+ */
+export interface PocketHookWrappedResponse {
+    output: PocketHookResponse[];
+}
+/**
+ * Options for the response builder.
+ */
+export interface ResponseOptions {
+    /** Message to display. Required. */
+    msg: string;
+    /** Shortcut name to trigger. */
+    shortcut?: string;
+    /** Data payload for the shortcut. */
+    data?: Record<string, unknown>;
+    /** HTTPS URL. Will be validated. */
+    url?: string;
+}
+/**
+ * Parsed incoming request from PocketHook app.
+ */
+export interface ParsedRequest {
+    sessionId: string;
+    chatInput: string;
+}

package/dist/validation.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedRequest } from "./types.js";
+/**
+ * Parse and validate an incoming PocketHook request body.
+ * Expects a JSON array with one object: [{ sessionId, action, chatInput }]
+ *
+ * @param body - Raw request body (string, Buffer, or already parsed object)
+ * @returns Parsed request with sessionId and chatInput
+ * @throws Error if the request format is invalid
+ */
+export declare function parseRequest(body: unknown): ParsedRequest;
+/**
+ * Validate that a URL is HTTPS.
+ * PocketHook only accepts HTTPS URLs.
+ */
+export declare function validateHttpsUrl(url: string): string;
+/**
+ * Extract the Bearer token from an Authorization header.
+ *
+ * @param header - The Authorization header value
+ * @returns The token string, or null if not a Bearer token
+ */
+export declare function extractBearerToken(header: string | null | undefined): string | null;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pockethook-sdk",
+  "version": "0.1.0",
+  "description": "SDK for building PocketHook-compatible server responses",
+  "module": "src/index.ts",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bunx --bun bun build src/index.ts --outdir dist --target node && bunx tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "pockethook",
+    "ios",
+    "shortcuts",
+    "automation",
+    "webhook",
+    "siri",
+    "n8n"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appflowmate/pockethook-sdk.git"
+  },
+  "homepage": "https://pockethook.app",
+  "bugs": {
+    "url": "https://github.com/appflowmate/pockethook-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export type {
+  PocketHookRequest,
+  PocketHookResponse,
+  PocketHookWrappedResponse,
+  ResponseOptions,
+  ParsedRequest,
+} from "./types.js";
+
+export {
+  response,
+  responses,
+  text,
+  shortcut,
+  toJSON,
+  toResponse,
+} from "./response.js";
+
+export {
+  parseRequest,
+  validateHttpsUrl,
+  extractBearerToken,
+} from "./validation.js";

package/src/response.ts

@@ -0,0 +1,110 @@
+import type { PocketHookResponse, ResponseOptions } from "./types.js";
+import { validateHttpsUrl } from "./validation.js";
+
+/**
+ * Build a single PocketHook response.
+ *
+ * @example
+ * ```ts
+ * response({ msg: "Hello!" })
+ * // => { msg: "Hello!" }
+ *
+ * response({ msg: "Done", shortcut: "BackupPhotos", data: { count: 42 } })
+ * // => { msg: "Done", shortcut: "BackupPhotos", data: { count: 42 } }
+ * ```
+ */
+export function response(options: ResponseOptions): PocketHookResponse {
+  if (!options.msg && options.msg !== "") {
+    throw new Error("msg is required");
+  }
+
+  const res: PocketHookResponse = { msg: options.msg };
+
+  if (options.shortcut !== undefined) {
+    if (typeof options.shortcut !== "string" || options.shortcut.length === 0) {
+      throw new Error("shortcut must be a non-empty string");
+    }
+    res.shortcut = options.shortcut;
+  }
+
+  if (options.data !== undefined) {
+    res.data = options.data;
+  }
+
+  if (options.url !== undefined) {
+    res.url = validateHttpsUrl(options.url);
+  }
+
+  return res;
+}
+
+/**
+ * Build an array of PocketHook responses (multi-action).
+ * PocketHook executes shortcuts sequentially in order.
+ *
+ * @example
+ * ```ts
+ * responses([
+ *   { msg: "Starting backup...", shortcut: "BackupPhotos" },
+ *   { msg: "Uploading...", shortcut: "UploadToCloud", data: { dest: "s3" } }
+ * ])
+ * ```
+ */
+export function responses(items: ResponseOptions[]): PocketHookResponse[] {
+  if (items.length === 0) {
+    throw new Error("At least one response is required");
+  }
+  return items.map(response);
+}
+
+/**
+ * Build a simple text-only response.
+ *
+ * @example
+ * ```ts
+ * text("Hello from the server!")
+ * // => [{ msg: "Hello from the server!" }]
+ * ```
+ */
+export function text(msg: string): PocketHookResponse[] {
+  return [response({ msg })];
+}
+
+/**
+ * Build a response that triggers a Shortcut.
+ *
+ * @example
+ * ```ts
+ * shortcut("Play Music", "PlaySpotify", { playlist: "chill" })
+ * // => [{ msg: "Play Music", shortcut: "PlaySpotify", data: { playlist: "chill" } }]
+ * ```
+ */
+export function shortcut(
+  msg: string,
+  name: string,
+  data?: Record<string, unknown>
+): PocketHookResponse[] {
+  return [response({ msg, shortcut: name, data })];
+}
+
+/**
+ * Serialize responses to a JSON string ready to send.
+ * Returns the standard PocketHook array format.
+ */
+export function toJSON(items: PocketHookResponse[]): string {
+  return JSON.stringify(items);
+}
+
+/**
+ * Create a Response object ready to return from a server handler.
+ * Sets Content-Type to application/json.
+ */
+export function toResponse(
+  items: PocketHookResponse[],
+  status = 200
+): Response {
+  return new Response(toJSON(items), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}

package/src/types.ts

@@ -0,0 +1,54 @@
+/**
+ * PocketHook standard request format.
+ * Sent as a JSON array: [PocketHookRequest]
+ */
+export interface PocketHookRequest {
+  sessionId: string;
+  action: "sendMessage";
+  chatInput: string;
+}
+
+/**
+ * A single response action from the server.
+ * The server returns an array of these: PocketHookResponse[]
+ */
+export interface PocketHookResponse {
+  /** Message to display in the chat. Required. */
+  msg: string;
+  /** iOS Shortcut name to trigger. Optional. */
+  shortcut?: string;
+  /** Arbitrary data payload passed to the Shortcut. Optional. */
+  data?: Record<string, unknown>;
+  /** HTTPS URL to associate with the response. Optional. Must be HTTPS. */
+  url?: string;
+}
+
+/**
+ * Server response wrapped in an "output" array.
+ * Alternative format: [{ output: [PocketHookResponse] }]
+ */
+export interface PocketHookWrappedResponse {
+  output: PocketHookResponse[];
+}
+
+/**
+ * Options for the response builder.
+ */
+export interface ResponseOptions {
+  /** Message to display. Required. */
+  msg: string;
+  /** Shortcut name to trigger. */
+  shortcut?: string;
+  /** Data payload for the shortcut. */
+  data?: Record<string, unknown>;
+  /** HTTPS URL. Will be validated. */
+  url?: string;
+}
+
+/**
+ * Parsed incoming request from PocketHook app.
+ */
+export interface ParsedRequest {
+  sessionId: string;
+  chatInput: string;
+}

package/src/validation.ts

@@ -0,0 +1,92 @@
+import type { ParsedRequest } from "./types.js";
+
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Parse and validate an incoming PocketHook request body.
+ * Expects a JSON array with one object: [{ sessionId, action, chatInput }]
+ *
+ * @param body - Raw request body (string, Buffer, or already parsed object)
+ * @returns Parsed request with sessionId and chatInput
+ * @throws Error if the request format is invalid
+ */
+export function parseRequest(body: unknown): ParsedRequest {
+  let parsed: unknown;
+
+  if (typeof body === "string") {
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      throw new Error("Invalid JSON in request body");
+    }
+  } else if (body instanceof ArrayBuffer || body instanceof Uint8Array) {
+    try {
+      const text = new TextDecoder().decode(body);
+      parsed = JSON.parse(text);
+    } catch {
+      throw new Error("Invalid JSON in request body");
+    }
+  } else {
+    parsed = body;
+  }
+
+  // PocketHook sends requests as an array
+  const arr = Array.isArray(parsed) ? parsed : [parsed];
+
+  const item = arr[0];
+  if (!item || typeof item !== "object") {
+    throw new Error("Request must contain at least one object");
+  }
+
+  const obj = item as Record<string, unknown>;
+
+  const sessionId = obj.sessionId;
+  if (typeof sessionId !== "string" || !UUID_REGEX.test(sessionId)) {
+    throw new Error("sessionId must be a valid UUID");
+  }
+
+  const chatInput = obj.chatInput;
+  if (typeof chatInput !== "string" || chatInput.length === 0) {
+    throw new Error("chatInput must be a non-empty string");
+  }
+
+  if (chatInput.length > 10_000) {
+    throw new Error("chatInput exceeds 10,000 character limit");
+  }
+
+  return { sessionId, chatInput };
+}
+
+/**
+ * Validate that a URL is HTTPS.
+ * PocketHook only accepts HTTPS URLs.
+ */
+export function validateHttpsUrl(url: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  if (parsed.protocol !== "https:") {
+    throw new Error(`URL must be HTTPS, got: ${parsed.protocol}`);
+  }
+
+  return url;
+}
+
+/**
+ * Extract the Bearer token from an Authorization header.
+ *
+ * @param header - The Authorization header value
+ * @returns The token string, or null if not a Bearer token
+ */
+export function extractBearerToken(
+  header: string | null | undefined
+): string | null {
+  if (!header) return null;
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  return match?.[1] ?? null;
+}