@nightowlsdev/integration-native

Adapter/Tooling

The fully-open DEFAULT IntegrationProvider backend, self-run OAuth, an authed auto-refreshing proxy, provider-direct webhooks, and a minimal poller, with credentials on your own infrastructure (no vendor catalog, no Nango).

What it does

@nightowlsdev/integration-native is the batteries-included, zero-vendor `IntegrationProvider` backend (the seam lives in `@nightowlsdev/connectors`). It turns hand-authored `defineConnector` defs into a working backend with credentials on YOUR infrastructure. `nativeProvider(opts)` implements: self-run OAuth (builds the PKCE + `state` authorization URL, exchanges the code, stores tokens in an injected `TokenVault`; OAuth2 uses the connector's inline endpoints, OIDC auto-discovers from the issuer, `oauth4webapi` is confined to this package so the engine wall holds); an authed proxy (`executeTool` calls a connector's declarative `op` with the vaulted token, auto-refreshing on known expiry and reactively on a 401, then fencing output, credential failures raise `ConnectorConnectionError` → re-auth, `429/502/503/504` raise `ConnectorRetryableError` → back off); provider-direct webhooks (`handleInboundWebhook` verifies the provider's own signature against a rotation-aware `WebhookSecretStore`, normalizes via the connector's event spec, returns a `TriggerEvent`); and `createNativePoller`, a host-scheduled (cron / Trigger.dev, no in-engine timers) driver that polls webhook-less providers a page at a time into CN8's `handleSyncEvent`, fail-safe and cursor-advancing only after delivery. Everything stateful, vault, connection persistence, per-provider OAuth app creds, the single-use PKCE/state store, the webhook verify scheme, the cursor store, is injected, so the package stays hermetically unit-testable and the host owns its storage. Engine-wall clean: peer-depends only on `@nightowlsdev/connectors`.

Install

pnpm add @nightowlsdev/integration-native

Key exports

nativeProvider
createNativePoller
types: NativeProviderOpts, NativePollerOpts, PollTarget, SyncCursorStore

Usage

integration-native.ts

import { nativeProvider, createNativePoller } from "@nightowlsdev/integration-native";
import { materializeIntegration } from "@nightowlsdev/connectors";
import { defineSwarm } from "@nightowlsdev/core";

// The fully-open default IntegrationProvider backend, self-run OAuth, credentials on YOUR infra.
const provider = nativeProvider({
  connectors: [githubConnector, slackConnector], // your hand-authored defineConnector defs
  vault,                 // @nightowlsdev/storage-supabase makeTokenVault, or your own TokenVault
  persistConnection,     // write the authoritative owl_connections row (backend: "native")
  oauthClient,           // (provider) => { clientId, clientSecret?, redirectUri } from env
  stateStore,            // single-use PKCE/state store
  baseUrlFor: (p) => API_BASES[p],
  webhook: { secrets, verify, parse }, // optional: provider-direct webhooks (rotation-aware)
});

// Grant the provider's tools to agents by skillNames (same seam as materializeConnectors).
const swarm = defineSwarm({ agents, connectorTools: materializeIntegration(provider, ctxToRefs) });

// Poll webhook-less providers on your own schedule (cron / Trigger.dev, no in-engine timers).
const poller = createNativePoller({ provider, targets, intake, cursors });