SDKs

Summary

Eigenn generates its SDKs from the current public OpenAPI document. They give typed resource clients, request models, response models, and bearer authentication for public API v1.

Capabilities

Generated Resource Groups

The generated clients include resource groups for customers, invoices, recurring invoices, transactions, bank accounts, documents, and inbox items. They also include reports, metrics, tags, tracking, teams, users, chat, search, notifications, OAuth, integration callbacks, and other operations that OpenAPI contains.

Two groups need care:

• WorkflowsApi covers executeWorkflow, chatWorkflow, and getWorkflowRun. It starts a run and polls it. It does not create, edit, or deploy a workflow. See Workflows API.
• WebhooksApi represents first-party provider callback endpoints. It does not manage outbound subscriptions. See Webhooks API Status.

Use the focused API pages to understand these limits before you depend on a generated class name.

Prerequisites

Available Clients

The current generated contract and source SDKs are versioned 1.0.0. Version strings alone do not prove that an installed release contains every current operation; compare the method and model you need with the current API reference.

Concepts

Keep the Client Current

1. Pin the SDK version in your dependency manager.
2. Read the public API changelog before you upgrade.
3. Regenerate or upgrade when the OpenAPI contract changes.
4. Run contract tests against sandbox.
5. Confirm the necessary scopes for every operation that your integration calls.

Workflow

Install a Client

The TypeScript 1.0.0 package is published on npm:

npm install @oppulence/[email protected]

Python and Rust have generated source clients, but their named packages were not available from public PyPI or crates.io during this documentation check. The Go module was also unavailable from the public module proxy. Obtain an authorized SDK source checkout or release artifact before using those clients; do not assume an unqualified registry install will work.

From a source checkout, Python can be installed with:

pip install ./sdk/python

For Rust, add a path dependency pointing to the SDK directory you obtained:

[dependencies]
oppulence-canvas-sdk = { path = "../oppulence-canvas/sdk/rust" }

For Go, configure repository access and pin the module revision supplied with your SDK distribution. A public-proxy 404 does not prove that an authorized direct repository fetch is available.

TypeScript Example

Pass either an Eigenn API key or an OAuth access token through accessToken. The generated client sends it as an Authorization bearer token.

import {
  Configuration,
  CustomersApi,
} from "@oppulence/canvas-sdk";

const token = process.env.EIGENN_API_TOKEN;

if (!token) {
  throw new Error("EIGENN_API_TOKEN is required");
}

const configuration = new Configuration({
  accessToken: token,
  basePath: "https://api.eigenn.io/v1",
});

const customers = new CustomersApi(configuration);
const page = await customers.listCustomers({ pageSize: 25 });

console.log(page.meta.hasNextPage);

This example requires customers.read. Keep the token in a server-side secret store. Do not initialize a privileged client in browser code. The generated client passes the supplied access token; it does not obtain or refresh OAuth credentials for you.

Choose the Environment

Set the base URL explicitly in long-lived integrations. Confirm that the credential and the test data belong to the intended environment before you send a write.

Behavior specification

Pagination and Errors

Generated clients model the same cursor response used by the REST API:

• the results are in data
• the next opaque cursor is in meta.cursor
• meta.hasNextPage tells you whether to continue
• meta.hasPreviousPage describes the current page

Do not construct or decode cursors. Pass the returned cursor to the next request and keep filters/sort unchanged. A full final page can be followed by an empty page. Repeated reads are not snapshots; deduplicate stored records by ID.

Each generated client exposes errors according to its language runtime. In TypeScript, non-2xx responses throw ResponseError with the underlying Response in error.response. Read its status and headers before parsing the body. A transport failure instead raises FetchError when no middleware supplies a replacement response.

TypeScript methods ending in Raw, such as listCustomersRaw, expose raw headers through result.raw and parsed data through await result.value(). The default runtime does not automatically paginate, retry, or refresh tokens; implement bounded behavior appropriate to the operation. Keep Retry-After and request IDs, without logging bearer tokens or customer payloads.

Idempotent Writes

Authenticated write operations documented in OpenAPI accept an optional Idempotency-Key header with a maximum length of 128 characters. The generated methods show that header as an operation parameter.

Reuse a key only for the same logical write. Eigenn can replay a successful response for that identity, method, path, query, and key. The body is not compared: changing it under the same key can replay the old success. Only successful 2xx responses are cached, for 24 hours. A failed write can already have persisted, so check state before retrying. Generated types do not fix server-side limitations such as the current Customers API response mismatch.

Diagrams

Screenshots

Not applicable: SDK installation and API calls run in application code. This guide does not describe an Eigenn interface.

Verification

1. Install the pinned TypeScript release or obtain the authorized source distribution for another language. Confirm the package and needed methods are present; record the exact version or revision.
2. Provide a valid API key or OAuth token, then initialize the client, catching and confirming any missing credential errors.
3. Set the base URL to the sandbox environment, perform a simple read operation (such as listing customers), and confirm you receive valid response data with correct pagination metadata.
4. Attempt a write operation with an Idempotency-Key header, verify you receive a response (or correct idempotent replay if retried with the same key and identical payload).
5. In an isolated fixture, verify that changing a body while reusing a cached key does not prove a new write occurred. For a genuinely new operation, use a new key and check persisted state.
6. Intentionally provoke an error (such as using an invalid token) to ensure error status and message are accessible.
7. Review changelog and pin your dependency before upgrading, regenerating, or deploying in production.

Related

Related Pages

• Authentication
• Pagination
• Rate Limits
• Errors
• Developer API Setup