How connectors work
Call an HTTP API from an asset.
A connector is a typed client for an HTTP API. The pipeline calls it through ctx.connection(). Config and secrets arrive from the binding when the attempt starts. The client does not declare assets.
Public npm adapters are @puppi/adapter-filesystem, @puppi/adapter-http, @puppi/adapter-podcast-index, @puppi/adapter-podcast-rss, @puppi/adapter-postgres, and @puppi/adapter-s3. The catalog also lists 24 connectors from this repository that are not on npm. Publication is separate from whether a connector’s client works. Each package is named @puppi/adapter-<type>.
Register a connector
Pass the module to defineConfig. The module’s default export is the connector definition, and it exports Client. defineConfig registers that class in the bundle the engine runs.
import * as http from "@puppi/adapter-http";
import * as postgres from "@puppi/adapter-postgres";
import { defineConfig } from "@puppi/sdk";
export default defineConfig({
connections: {
api: http,
warehouse: postgres,
},
}); filesystem and s3 are the same shape. Registering the module is enough. The pipeline does not import Client; the executor constructs it.
Two connection names may share one module. A second, different client for the same type is refused.
Call it from an asset
The name in ctx.connection() is the connection name from the config, and it has to be a string literal. The CLI records that literal, and the engine resolves a binding for it. @puppi/adapter-http get(path, params) sends GET <base_url><path> and decodes the body as JSON.
import { source } from "@puppi/sdk";
import { z } from "zod";
const Item = z.object({
id: z.string(),
});
export const item = source({
key: "api/item",
schema: Item,
run: async (ctx) => {
const api = ctx.connection("api");
const body = await api.get<{ id: string }>("/items/1");
await ctx.emit([body]);
},
}); A catalog list method yields { cursor, data }. cursor is the next page token, or null on the last page. An append source’s cursor field is the watermark column on the row.
ctx.connection() returns unknown until puppi build has written puppi-env.d.ts and the project can resolve @puppi/adapter-<type>.
Bind credentials
puppi.config.ts names the connection and its type. The binding says where it is reached, and which secrets it uses. puppi try reads bindings.local.json. puppi env bind writes the same facts to an environment that is already running. The commands below need a declared api connection of type http, --env or PUPPI_ENV, and HTTP_TOKEN set in the shell.
puppi env secret http_token --env prod --from-env HTTP_TOKEN
puppi env bind api --env prod \
--config '{"base_url":"https://api.example.com"}' \
--secret-ref bearer_token=http_token \
--type http The secret’s value goes in and does not come back. puppi env show lists secret names and versions. The pipeline never receives the value. The client does, as a constructor argument.
A binding may omit api_version when the connector has a default. Any other value, one the package does not list, fails when the client is constructed.
To add a connector, use puppi connector new.