@hitch42/applet 0.1.0-beta.10

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@hitch42/applet",
+  "version": "0.1.0-beta.10",
+  "license": "MIT",
+  "bin": {
+    "applet": "./dist/applet.js"
+  },
+  "files": [
+    "dist",
+    "scaffold"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "source": "./src/author/server.ts",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "source": "./src/author/client.ts",
+      "default": "./dist/client.js"
+    },
+    "./react": {
+      "source": "./src/react/index.ts",
+      "default": "./dist/react.js"
+    },
+    "./telephony": {
+      "source": "./src/telephony/index.ts",
+      "default": "./dist/telephony.js"
+    },
+    "./vite": {
+      "source": "./src/vite.ts",
+      "default": "./dist/vite.js"
+    },
+    "./_internal/client": {
+      "source": "./src/internal/client.ts",
+      "default": "./dist/_internal/client.js"
+    },
+    "./_internal/server": {
+      "source": "./src/internal/server.ts",
+      "default": "./dist/_internal/server.js"
+    }
+  },
+  "dependencies": {
+    "@cloudflare/vite-plugin": "^1.51.1",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@hey-api/openapi-ts": "0.0.0-next-20260824173136",
+    "@orpc/client": "^1.15.0",
+    "@orpc/contract": "^1.15.0",
+    "@orpc/openapi-client": "^1.15.0",
+    "@orpc/tanstack-query": "^1.15.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "@tanstack/react-query-persist-client": "5.101.4",
+    "@tanstack/router-cli": "^1.167.24",
+    "@tanstack/router-plugin": "^1.168.23",
+    "@telnyx/webrtc": "^2.27.10",
+    "@tiptap/core": "^3.30.3",
+    "@tiptap/extension-image": "^3.30.3",
+    "@tiptap/extension-list": "^3.30.3",
+    "@tiptap/extension-table": "^3.30.3",
+    "@tiptap/extensions": "^3.30.3",
+    "@tiptap/markdown": "^3.30.3",
+    "@tiptap/react": "^3.30.3",
+    "@tiptap/starter-kit": "^3.30.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "class-variance-authority": "^0.7.1",
+    "cn": "^0.4.0",
+    "croner": "^10.0.1",
+    "lucide-react": "^1.33.0",
+    "oxc-transform-react": "^0.149.0",
+    "oxfmt": "^0.72.0",
+    "oxlint": "^1.87.0",
+    "oxlint-tsgolint": "^7.0.2003",
+    "react-aria-components": "^1.20.0",
+    "shadcn": "^4.16.1",
+    "smol-toml": "^1.9.0",
+    "streamdown": "^2.6.0",
+    "tailwindcss": "^4.3.0",
+    "tw-animate-css": "^1.4.0",
+    "vite": "8.3.0",
+    "vitest": "4.1.11",
+    "wrangler": "^4.120.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@orpc/server": "^1.15.0",
+    "@tanstack/react-query": "5.101.4",
+    "@tanstack/react-router": "^1.170.18",
+    "@types/node": "^24",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hitch-42/hitch.git",
+    "directory": "packages/applet"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "beta"
+  }
+}

package/scaffold/.agents/skills/hitch-applets/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: hitch-applets
+description: Build, change, test, and debug Hitch applets. Use for applet routes, Hitch data access, applet servers, contract and theme generation, local development, deployment, and applet UI work.
+---
+
+# Hitch Applets
+
+Build small applets against an organization's Hitch data. Keep each applet focused on one related workflow.
+
+Treat each applet as an isolated microfrontend. Keep it separate from the data storage layer, and access Hitch data through the SDK.
+
+## Go deeper
+
+This file holds the common rules. Read each matching reference before you edit an applet. Paths are relative to this file.
+
+| Read this                      | When the task involves                                                                                   |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `references/client.md`         | Client routes, navigation, page layout, forms, controls, or other user interface work                    |
+| `references/records.md`        | Listing, querying, creating, or updating records; filters, includes, aggregates; a missing record method |
+| `references/files.md`          | Uploading or reading files, attachment attributes, download links                                        |
+| `references/email-tracking.md` | Creating pixels and reading raw email hits                                                               |
+| `references/markdown.md`       | Rendering or editing markdown, image uploads, Hitch file links                                           |
+| `references/server.md`         | The applet server: secrets, env variables, external services, the `api` client                           |
+| `references/schedules.md`      | Cron schedules and background runs                                                                       |
+| `references/workflows.md`      | Multi-step server work: `createWorkflow`, `step.do`, `step.sleep`, starting, reading, and listing runs   |
+| `references/manifest.md`       | The applet definition in `applet.manifest.ts`: objects, access, variables, and packages                  |
+| `references/performance.md`    | Data access design: client versus server, N+1 reads, includes, aggregates, pagination, batch writes      |
+
+For attribute types, filters, and API limits, read `../hitch-data/SKILL.md`. To inspect or change Hitch data and settings from the shell, read `../hitch-cli/SKILL.md`.
+
+Read `../tanstack-router/SKILL.md` for route work and `../tanstack-query/SKILL.md` for query and cache work.
+Read `../react-best-practices/SKILL.md` for React performance and `../web-design-guidelines/SKILL.md` for requested interface reviews.
+Follow the Hitch applet rules for SDK-owned configuration, providers, and generated files.
+
+## Work with the workspace
+
+- Run package commands with `pnpm`.
+- Run `pnpm exec applet login` from the workspace root or an applet directory to sign in. It uses the organization in `hitch.config.ts` and shares credentials with `hitch login`. Add `--no-browser` to print the sign-in URL without opening a browser.
+- A server permission error is not a login request.
+- After a workspace is linked to a repository, deploy in two ways. Run `pnpm exec applet deploy` to release a change immediately. Push to the production branch to deploy through CI and keep releases in sync with the repository.
+- Run `pnpm exec applet new <code>` from the workspace root to create a full applet.
+- Add `--client-only` or `--server-only` when the applet needs only one part.
+- Use `--client-only` for a user interface that uses the current user's Hitch access and needs no server.
+- Use `--server-only` for an API or schedule that needs no user interface.
+- The `new` command creates the applet before it installs packages and generates Hitch types.
+- If installation or generation fails, inspect the created applet. Do not run `new` again.
+- Run `pnpm install`, then rerun `pnpm exec applet generate` from the applet directory.
+- If the user selects `--no-install`, do not run package scripts until applet dependencies are available.
+- If generation cannot select a saved login, ask the user to fix the login or provide `HITCH_API_KEY`.
+- Do not install or run a different Hitch CLI to repair applet generation.
+- Run `pnpm --dir applets/<code> run generate` after a Hitch object, operation, or theme changes.
+- Run generation at the start of a session when the task depends on current Hitch types.
+- Run `pnpm --dir applets/<code> run dev` and `pnpm --dir applets/<code> run build` from the workspace root.
+- The dev server runs as you in the production org. Reads and writes use real data.
+- The dev server prints a preview link. Open the link to see the local applet inside Hitch.
+- Chrome asks once to allow local network access for the Hitch site.
+- The preview lasts until you select Exit or close the tab.
+- A pending `requiresChangeset` schema is not available in dev. Deploy to test it.
+- Run `pnpm --dir applets/<code> run deploy` only when the user requests a deployment.
+- The CLI creates missing MCP files and adds missing Hitch and Chrome DevTools entries. Existing entries and other settings belong to the user.
+- The applet CLI replaces its generated support files. It creates `.github/workflows/hitch.yml` only when the file is absent. To stop it, set `githubWorkflow: false` in `hitch.config.ts` and delete the file.
+- Remember that generation refreshes the local theme copy. Deployed applets load the public org theme from its Hitch `.com` URL.
+
+## Use Vite and Vitest
+
+- Import configuration APIs from `vite`.
+- Import test APIs from `vitest`.
+- Put tests in the applet's `test` folder and name them `*.test.ts` or `*.test.tsx`. Vitest does not run test files in other folders.
+- Do not edit `vite.config.ts`. The applet CLI rewrites it. Do not add another Vite config.
+- Add applet packages to `dependencies` or `devDependencies` in `applet.manifest.ts`.
+
+## Access Hitch data
+
+Use the client SDK unless the task needs a secret or an external service:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+import { hitch } from "@hitch42/applet/client";
+
+const deals = useQuery(
+  hitch.records.deals.list.queryOptions({
+    input: { query: {} },
+  }),
+);
+```
+
+The client SDK uses the current user's identity and access. Do not add a server proxy for filtering or access control.
+
+Use the server SDK for secrets, external services, or imperative Hitch data access:
+
+```ts
+import { env, hitch } from "@hitch42/applet/server";
+```
+
+Define an applet server with an oRPC router:
+
+```ts
+import { os } from "@orpc/server";
+
+const router = {
+  hello: os.handler(() => ({ hello: "World!" })),
+};
+
+export default { router };
+```
+
+Call applet server procedures through the generated client API:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+import { api } from "@hitch42/applet/client";
+
+const greeting = useQuery(api.hello.queryOptions());
+```
+
+Use generated types as the source of truth. Do not add casts or local copies that bypass them.
+
+Do not invent fields or silence type errors with casts. Ask the user when generated types exclude a requested field or operation.
+
+## Work with files
+
+Upload a file with one call. The SDK creates the file record and sends the bytes directly to storage:
+
+```ts
+import { hitch } from "@hitch42/applet/client";
+
+const uploaded = await hitch.files.upload(file); // file is a web File
+```
+
+Read `references/files.md` before download links, attachment attributes, or server-side uploads.
+
+## Diagnose with logs
+
+- Add useful `console.<level>` calls around important server work and failures. Deployed logs often provide the clearest evidence for applet issues.
+- Choose `console.log`, `console.info`, `console.warn`, or `console.error` deliberately. The console method sets the entry level used by log filters.
+- Run `pnpm --dir applets/<code> exec applet logs --filter '{"type":"applet"}'` from the workspace root to inspect applet code logs.
+- Include the applet type filter during diagnosis. Without it, Cloudflare invocation entries can hide the useful applet entries. For a workflow run, use `--run <id>` or `--filter '{"type":"workflow"}'` instead.
+- Do not log secrets, tokens, or personal data.
+
+## Verify changes
+
+Run these commands from the workspace root before deployment:
+
+```sh
+pnpm --dir applets/<code> run generate
+pnpm --dir applets/<code> run typecheck
+pnpm --dir applets/<code> run fmt
+pnpm --dir applets/<code> run lint
+pnpm --dir applets/<code> run test # Only when the applet contains tests.
+pnpm --dir applets/<code> run build
+```
+
+If missing packages block a check, stop package checks. Do not retry the check through another binary.
+
+If a command fails, report the exact blocker. Do not deploy as a verification step.
+
+## Deploy from GitHub
+
+- A push to the production branch runs `applet deploy` in the workspace root through GitHub Actions.
+- An applet deploys when its own folder changed since its current CI release. Every applet deploys when a file outside `applets/` changed. An applet without a CI release always deploys. An applet also deploys when CI cannot load the commit of its current release.
+- The deploy skips other applets and logs the reason. A skip is expected, not a failure.
+- A schema change in Hitch alone does not trigger CI.
+- Do not import from a sibling applet folder. The change check does not follow such imports.

package/scaffold/.agents/skills/hitch-applets/references/client.md

@@ -0,0 +1,73 @@
+# Client routes and interface
+
+Read this file before you change client routes, navigation, page layout, forms, or controls.
+
+## Choose the client half
+
+- Use a client-only applet for a user interface that uses the current user's Hitch access.
+- Add a server only for secrets, external services, schedules, or imperative server work.
+- Do not add a server proxy for normal Hitch data access.
+
+## Define routes
+
+Hitch mounts each applet below `/<code>`. Include the applet code in every route path.
+
+Use these file and path pairs:
+
+| File                                   | Route path          |
+| -------------------------------------- | ------------------- |
+| `src/client/routes/index.tsx`          | `/<code>/`          |
+| `src/client/routes/about.tsx`          | `/<code>/about`     |
+| `src/client/routes/settings/index.tsx` | `/<code>/settings/` |
+
+Define a page with `createFileRoute`:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/<code>/about")({
+  component: AboutPage,
+});
+
+function AboutPage() {
+  return <main>About</main>;
+}
+```
+
+- Keep the generated route path type as the source of truth.
+- If TypeScript rejects a route, check its file name and `/<code>` prefix.
+- Do not use a cast to bypass a route error.
+
+## Add navigation
+
+Use TanStack Router's `Link` for a normal internal link:
+
+```tsx
+import { Link } from "@tanstack/react-router";
+
+<Link to="/<code>/about">About</Link>;
+```
+
+Use the bundled `LinkButton` for a button-style link:
+
+```tsx
+import { LinkButton } from "@/client/components/ui/button";
+
+<LinkButton href="/<code>/about">About</LinkButton>;
+```
+
+- Use a full path that starts with the applet code.
+- Use `LinkButton` for button-style navigation. Use `Button` for an action.
+- Do not add extra navigation that the user did not request.
+
+## Use the interface components
+
+- Use components in `src/client/components/ui` before raw HTML controls.
+- Inspect a component export before you use it.
+- Browse the [shadcn component catalog](https://ui.shadcn.com/docs/components) before you create a control.
+- Prefer a shadcn React Aria component when the catalog has a suitable component.
+- Run `pnpm exec shadcn add <component>` from the applet directory to add a missing component.
+- Keep installed components unchanged when possible.
+- Copy a component outside the `ui` directory before a product-specific change.
+- Use `cn` from `@/client/lib/utils` for class names.
+- Keep global styles in `src/client/styles/globals.css`.

package/scaffold/.agents/skills/hitch-applets/references/email-tracking.md

@@ -0,0 +1,49 @@
+# Email tracking
+
+Create one pixel for each email. Put its URL in the HTML before send.
+Add the pixel next to CID images. A CID image cannot make a tracking request.
+
+```ts
+const { id, url } = await hitch.email.tracking.createPixel({
+  tags: { campaignId: "fall", buyerId: "acme", version: "v2" },
+});
+const html = `<p>Hello</p><img src="${url}" width="1" height="1" alt="">`;
+// Send the email with the applet's email provider.
+await hitch.email.tracking.markSent({ id });
+```
+
+`markSent({ id, sentAt })` accepts an ISO time. A later call replaces the sent time.
+`get({ id })` returns one tracker. `list()` returns up to 100 trackers by default.
+Use `filter`, `sentAt`, `cursor`, and `limit` to select a page.
+
+```ts
+const tracker = await hitch.email.tracking.get({ id });
+const query = {
+  filter: { buyerId: "acme" },
+  sentAt: { $gte: "2026-10-01T00:00:00Z" },
+  limit: 100,
+};
+const page = await hitch.email.tracking.list(query);
+const next = page.nextCursor
+  ? await hitch.email.tracking.list({ ...query, cursor: page.nextCursor })
+  : null;
+const opened =
+  tracker.lastHitAt !== null &&
+  new Date(tracker.lastHitAt).getTime() >
+    new Date(tracker.sentAt ?? tracker.createdAt).getTime() + 60_000;
+```
+
+The example rule counts a tracker as opened when `lastHitAt` is more than 60 seconds after send or creation.
+Hitch records `firstHitAt` and `lastHitAt`. It does not classify opens.
+Each page must repeat the same filter, `sentAt`, and limit.
+
+Tags stay fixed after creation. Use at most 10 tags. A key starts with an ASCII letter.
+The rest contains ASCII letters, digits, or underscores, up to 64 characters total.
+Each value has 1 to 200 characters. A filter matches every tag by exact equality.
+Everyone with applet access sees all its trackers.
+
+Gmail can fetch through `GoogleImageProxy` a few seconds after send.
+A real Gmail open has the same user agent. A Gmail draft preview can fetch before send.
+Apple Mail Privacy Protection fetches on delivery with `Mozilla/5.0`.
+That fetch looks like a real open. Proton fetches on delivery.
+Clients with images off never fetch the pixel.

package/scaffold/.agents/skills/hitch-applets/references/files.md

@@ -0,0 +1,109 @@
+# Files
+
+Use the file API to upload bytes, read file metadata, and link files to records.
+
+## Upload a file
+
+- Import `hitch` from the client or server SDK.
+- Call `hitch.files.upload(file)` with a web `File`.
+- Use the same upload call in the client and server halves.
+- Receive the complete file row plus a `downloadUrl` when the call resolves: storage has the bytes.
+- A failed upload throws an `Error` and leaves no usable id. Call `upload(file)` again to retry — the abandoned row is harmless.
+
+```ts
+import { hitch } from "@hitch42/applet/client";
+
+const uploaded = await hitch.files.upload(file);
+```
+
+Show progress or allow cancellation with the options argument:
+
+```ts
+const controller = new AbortController();
+
+const uploaded = await hitch.files.upload(file, {
+  signal: controller.signal,
+  onProgress: ({ loaded, total }) => setPercent(Math.round((100 * loaded) / total)),
+});
+```
+
+- `onProgress` reports uploaded bytes in the browser. The server half uploads without progress.
+- Abort the signal to cancel; the call rejects with an abort error.
+
+Use a TanStack mutation in a React component:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+import { hitch } from "@hitch42/applet/client";
+
+const upload = useMutation({
+  mutationFn: (file: File) => hitch.files.upload(file),
+});
+
+upload.mutate(file);
+```
+
+Use the server SDK for an imperative upload:
+
+```ts
+import { hitch } from "@hitch42/applet/server";
+
+const uploaded = await hitch.files.upload(file);
+```
+
+## Set the content type
+
+The browser sets `file.type` for picked files. On the server, set the type when you construct the `File`:
+
+```ts
+const file = new File([csvBytes], "report.csv", { type: "text/csv" });
+```
+
+An empty `file.type` uploads as `application/octet-stream`.
+
+## Read a file
+
+Use `download` when a component needs one fresh link without query state:
+
+```ts
+const file = await hitch.files.download(id);
+file.downloadUrl; // a download link, valid for at least a day
+```
+
+Use the `get` query utilities when React needs file metadata as query state.
+
+`get` returns `{ data, downloadUrl }`. Every file you can fetch is complete: `upload` resolves only after storage confirms the bytes. A file whose upload never finished answers 404 with code `file_not_arrived` — treat that id as dead and upload again.
+
+```ts
+const fileQuery = useQuery(
+  hitch.files.get.queryOptions({
+    input: { params: { id } },
+  }),
+);
+
+if (fileQuery.data) {
+  const { data: row, downloadUrl } = fileQuery.data;
+  row.filename; // "report.csv"
+  row.contentType; // "text/csv"
+  row.sizeBytes; // 1024
+  downloadUrl; // a download link, valid for at least a day
+}
+```
+
+A `downloadUrl` expires after 24 to 48 hours. Call `get` again for a fresh link instead of storing one.
+
+## Link a file to a record
+
+Store `uploaded.id` as the value of an attachment attribute. A multi-value attachment attribute takes an array of ids.
+
+```ts
+const uploaded = await hitch.files.upload(file);
+
+await hitch.records.claims.update.call({
+  params: { id: claimId },
+  body: { receipt_id: uploaded.id }, // multi-value: [uploaded.id]
+});
+```
+
+- Upload the file before the record write: the write rejects a missing id ("file not found") and a pending id ("file has not arrived").
+- Store the file id, never a URL — URLs expire.