@devosurf/tesser-connectors 0.1.0-alpha.3 → 0.1.0-alpha.4

package/README.md

@@ -6,7 +6,7 @@ The Tesser connector library. **Apache-2.0** — connectors are permissive so th
 >
 > `outlook-mail` supports delegated Microsoft 365 user mailboxes by default and shared mailbox operations via the optional `mailbox` input, which targets Graph `/users/{userPrincipalName}` endpoints. It includes message list/get/send/reply/move/read-state/category helpers, draft create/reply/update/send, attachment get/list, mail folder list, master category list/create, and a delta-query `messageReceived` poll trigger. Graph webhook subscriptions remain future work because the runtime must own `validationToken` echoing and renewal.
 
-A connector is **our own** typed artifact — no Nango, no third-party OAuth code (ADR-0004). One connector per directory (`connectors/<name>/index.ts` + colocated tests + `sampleData`); a codegen step owns the registry, so you never hand-edit a global file. Auth is declared **once** and injected into every Action as a pre-authed `ctx.http` client — the author **never names a token** (`ctx.auth` is a masked escape hatch for odd placements). Actions are nested typed calls that return *our* stable shape, which `output` validates — never the raw provider response (ADR-0012):
+A connector is **our own** typed artifact — no Nango, no third-party OAuth code (ADR-0004). One connector per directory (`connectors/<name>/index.ts` + colocated tests + `sampleData`); a codegen step owns the registry, so you never hand-edit a global file. The npm package intentionally ships `manifest.json`, `llms.txt`, and every connector `index.ts` so agents can inspect the installed, version-pinned source instead of relying on stale generated summaries. Auth is declared **once** and injected into every Action as a pre-authed `ctx.http` client — the author **never names a token** (`ctx.auth` is a masked escape hatch for odd placements). Actions are nested typed calls that return *our* stable shape, which `output` validates — never the raw provider response (ADR-0012):
 
 ```ts
 defineConnector({

package/llms.txt

@@ -0,0 +1,85 @@
+# @devosurf/tesser-connectors — installed Connector source map
+
+This package intentionally ships the installed Connector source as TypeScript. For exact Connector APIs, inspect the version-pinned files in `node_modules`; do not rely on training data, memory, or hand-written summaries.
+
+## Hard rule
+
+Do not guess Connector APIs from memory, training data, old examples, or web search. After `pnpm install`, inspect the installed package in `node_modules/@devosurf/tesser-connectors`.
+
+## Source-of-truth order for agents
+
+1. Project policy: `AGENTS.md` and `.tesser/docs/connectors.md`.
+2. Connector inventory: `node_modules/@devosurf/tesser-connectors/manifest.json`.
+3. Import names: `node_modules/@devosurf/tesser-connectors/index.ts`.
+4. Exact input/output schemas, samples, triggers, provider quirks: `node_modules/@devosurf/tesser-connectors/<connector-id>/index.ts`.
+5. Provider OAuth facts: `node_modules/@devosurf/tesser-connectors/providers/*.ts` and `catalog/index.ts`.
+
+Never edit `node_modules`. Read it, then edit the Automation under `automations/<id>/` and validate with `tesser test --json` / `tesser build --json`.
+
+## Quick inspection commands
+
+Run `pnpm install` first if `node_modules` is absent.
+
+```bash
+# Barrel export names: use these names in `import { ... } from "@devosurf/tesser-connectors"`.
+sed -n '1,180p' node_modules/@devosurf/tesser-connectors/index.ts
+
+# Installed connector inventory with actions/triggers.
+node - <<'NODE'
+const fs = require('node:fs');
+const manifest = JSON.parse(fs.readFileSync('node_modules/@devosurf/tesser-connectors/manifest.json', 'utf8'));
+for (const c of manifest.connectors) {
+  console.log("");
+  console.log(`${c.id}: ${c.describe}`);
+  const auth = Object.keys(c.auth ?? {});
+  if (auth.length) console.log(`  auth: ${auth.join(', ')}`);
+  if (c.actions?.length) console.log(`  actions: ${c.actions.map((a) => `${a.path} [${a.safety}${a.retrySafe ? ', retry-safe' : ''}]`).join(', ')}`);
+  if (c.triggers?.length) console.log(`  triggers: ${c.triggers.map((t) => `${t.id} [${t.strategy}]`).join(', ')}`);
+}
+NODE
+
+# Exact schemas for one Connector, including Zod input/output objects.
+sed -n '1,260p' node_modules/@devosurf/tesser-connectors/outlook-mail/index.ts
+```
+
+## Authoring pattern
+
+```ts
+import { defineAutomation, onSchedule } from "@devosurf/tesser-sdk";
+import { github, slack } from "@devosurf/tesser-connectors";
+import { z } from "zod";
+
+export default defineAutomation({
+  id: "digest",
+  trigger: onSchedule({ cron: "0 9 * * *", tz: "UTC" }),
+  connections: { github, slack },
+  output: z.object({ posted: z.boolean(), count: z.number() }),
+
+  run: async (_input, ctx) => {
+    const issues = await ctx.step("fetch-open-issues", () =>
+      ctx.connections.github.issues.list({ state: "open", labels: ["bug"] }),
+    );
+
+    if (issues.length === 0) return { posted: false, count: 0 };
+
+    await ctx.step("post-to-slack", () =>
+      ctx.connections.slack.chat.postMessage({ channel: "#ops", text: `${issues.length} bugs` }),
+    );
+
+    return { posted: true, count: issues.length };
+  },
+});
+```
+
+## Rules that matter more than the Connector API
+
+- A Connector import is not an authed client. It is a typed requirement declaration.
+- Runtime calls go through `ctx.connections.<connection-key>` inside `run`.
+- Every Connector Action call must be inside `ctx.step(...)`.
+- Declare raw credentials separately with `secrets: { name: secret({ describe: "..." }) }`.
+- The Credential broker injects values at runtime; agents must never read or print tokens/secrets.
+- Deploy halts on missing Connections or Secrets; a human completes the connect link.
+
+## Connector ids currently shipped in this package
+
+Read `manifest.json` for the authoritative list. Current ids include core HTTP/email/repo/chat/calendar/document/spreadsheet/model/harness Connectors such as `http`, `github`, `slack`, `resend`, `gmail`, `outlook-mail`, Google Connectors, and Harness/model Connectors. Do not hardcode this list in Automations or docs; inspect the installed manifest.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devosurf/tesser-connectors",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "Tesser connector library — typed integrations consumed as ctx.connections.<name>.",
   "license": "Apache-2.0",
   "type": "module",
@@ -14,13 +14,14 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@devosurf/tesser-sdk": "0.1.0-alpha.3"
+    "@devosurf/tesser-sdk": "0.1.0-alpha.4"
   },
   "devDependencies": {
-    "@devosurf/tesser-testing": "^0.1.0-alpha.3"
+    "@devosurf/tesser-testing": "^0.1.0-alpha.4"
   },
   "files": [
     "index.ts",
+    "llms.txt",
     "catalog/index.ts",
     "providers/*.ts",
     "*/index.ts",