Skip to content

Recipe: connector-satellite

A program on a customer’s own machine (the satellite) delivers files into the app without a user session. It pairs once through the OAuth device flow and then uses a revocable device token.

What the recipe demonstrates:

  • Mount createConnectorsFeature() and createConnectorRoutes() (as extraRoutes)
  • Pairing: the satellite asks for a code, a TenantAdmin confirms it through connectors:write:approve-device, the satellite collects its ksat_ token once
  • Upload: raw bytes plus relative path, SHA-256 and modification time; the same file again answers duplicate: true instead of creating a second item

The wire protocol for the satellite is in connectors-satellite.md.

samples/recipes/connector-satellite/
├── package.json
├── README.md
└── src/
├── feature.ts # the feature and its routes
└── __tests__/satellite.integration.test.ts # pair, confirm, upload twice
Terminal window
bun test --config=bunfig.integration.toml samples/recipes/connector-satellite/src/__tests__/satellite.integration.test.ts

The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):

import {
createConnectorRoutes,
createConnectorsFeature,
} from "@cosmicdrift/kumiko-bundled-features/connectors";
// The feature holds the pairing and intake logic; the routes are what the satellite talks to.
// Mount both: `features: [..., connectorsFeature]` and `extraRoutes: connectorRoutes`.
export const connectorsFeature = createConnectorsFeature();
export const connectorRoutes = createConnectorRoutes({ maxUploadBytes: 20 * 1024 * 1024 });

📄 On GitHub: samples/recipes/connector-satellite/src/feature.ts