Skip to Content
Puppi
Connectors

Create a connector

Scaffold a connector package with puppi connector new.

puppi connector new writes a connector package. You replace the placeholder OpenAPI document and register the module in defineConfig.

The type is a connection name: lowercase letters, digits, and dashes, starting with a letter. http is reserved and refused.

Create the package

Install the CLI as in the quickstart. Then:

  1. Scaffold the package. The default directory is the type name. --force overwrites files that are already there.

    puppi connector new acme
  2. Install and test.

    cd acme
    npm install
    npm test

    npm test checks that the package exports the source interface. It does not call a vendor, and it does not run generate. A passing test is not a vendor integration.

package.json is @puppi/adapter-acme at 0.1.0, with "private": true. Its runtime dependency is @puppi/sdk at ^0.3.0.

FileRole
package.json@puppi/adapter-<type>. Runtime dependency is @puppi/sdk.
src/define.tsdefineConnector: type, docs URL, auth, versions, config, secrets.
src/index.tsDefault-exports that definition and exports Client.
openapi.jsonA placeholder GET /ping. Replace it with the vendor’s document.
src/openapi.ts, src/operations.tsGenerated from openapi.json.
test/client.test.tsExport-interface check. See the npm test step above.
README.md, tsconfig.json, test/tsconfig.json, .gitignorePackage scaffolding.

Point it at the vendor

Replace openapi.json with the vendor’s document, trimmed to the operations this package calls. The generate script in package.json rewrites src/openapi.ts and src/operations.ts. Leave those two files generated.

Edit src/define.ts for the identity (docs URL, auth scheme, API versions, config, secrets) and src/index.ts for check() and the list methods. define.ts imports nothing generated. Client extends the HTTP client’s OpenApiClient and implements check(). A list method yields pages. An asset calls that method.

Register it

Register the module in defineConfig the same way as a catalog connector.