@nightowlsdev/connectors 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Night Owls contributors
+
+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,48 @@
+# @nightowlsdev/connectors
+
+The connector seam for Night Owls: declare an external service's **actions** (agent-callable tools) once, and materialize them into approval-gated, output-fenced `SwarmTool`s over a pluggable **backend** (env/static now; Nango/OAuth and remote-MCP later) — with no agent-code change when the backend swaps.
+
+Engine-wall clean: depends only on `@nightowlsdev/core` + `zod` (no Mastra types in the public surface).
+
+## Usage
+
+```ts
+import { z } from "zod";
+import { defineConnector, staticBackend } from "@nightowlsdev/connectors";
+
+// 1. Declare the connector (plain validated data).
+const slack = defineConnector({
+  provider: "slack",
+  actions: [
+    { name: "slack.post_message", inputSchema: z.object({ channel: z.string(), text: z.string() }),
+      op: { method: "POST", path: "/chat.postMessage" } },                 // side-effecting → needsApproval defaults true
+    { name: "slack.search", inputSchema: z.object({ q: z.string() }),
+      needsApproval: false, op: { method: "GET", path: "/search.messages" } }, // read-only
+  ],
+});
+
+// 2. Pick a backend. `staticBackend` is the zero-infra dev/test backend (creds from env/config).
+const backend = staticBackend({
+  connections: { slack: { baseUrl: "https://slack.com/api", secretRef: "slack-bot-token" } },
+  secrets,  // a SecretResolver (resolved at execute time, scoped by the run's tenant)
+});
+
+// 3. Materialize the actions into SwarmTools (e.g. to grant an agent). Each tool:
+//    - runs through the SP5 approval gate (needsApproval),
+//    - resolves the connection's credential at execute time,
+//    - FENCES its untrusted output before it reaches the model.
+const tools = await backend.materialize(slack, ctx);
+```
+
+## What's here (K1)
+
+- `defineConnector` — the declarative DSL (provider + actions + optional events; validated).
+- `ConnectorBackend` / `BoundConnection` / `ConnectionRef` — the pluggable-backend seams.
+- `staticBackend` — env/config credentials + a bearer-token HTTP proxy; the zero-infra reference backend.
+- `fenceConnectorOutput` — the per-backend output-fencing contract.
+
+## Roadmap (follow-on)
+
+- Core wiring: an async, request-context-aware connector-tool resolver for root **and** sub-agents + `defineSwarm({ connectors, backend })`.
+- Slack/Linear/Email connectors; trigger intake (`handleTriggerEvent`); out-of-band human-in-the-loop delivery.
+- `nangoBackend` (per-user OAuth) — see `docs/superpowers/specs/2026-06-15-connectors-architecture-design.md`.