#SDK overview

@coduck/sdk is the official SDK for apps deployed on CoDuck. It gives your project auth, forms, file storage, and analytics backed by the platform — no separate backend to stand up.

When CoDuck generates and deploys your project, the SDK is already installed and configured. You just import the module you need.

#Install

In a CoDuck-deployed project the SDK and its env vars are wired up automatically. To add it to a project by hand:

bash

npm install @coduck/sdk

npm install @coduck/sdk

#How it configures itself

At deploy time CoDuck injects these env vars, and the SDK reads them automatically — you rarely construct a client yourself:

Variable	Scope	Purpose
`CODUCK_API_KEY`	server only	Authenticates server-side calls (forms read, storage, analytics, project meta)
`CODUCK_AUTH_KEY`	server only	Tenant key for auth. Only injected on deploy — auth does not work in the in-editor preview
`CODUCK_PROJECT_ID` / `NEXT_PUBLIC_CODUCK_PROJECT_ID`	server / browser	Identifies your project
`CODUCK_API_URL` / `NEXT_PUBLIC_CODUCK_API_URL`	server / browser	SDK API base (defaults to `https://api.coduck.ai/sdk`)

Server vs. browser. Most SDK calls require CODUCK_API_KEY, so they must run on the server (route handlers, server actions, server components). The only browser-safe call is forms.submit(). Auth additionally needs CODUCK_AUTH_KEY, which means sign-in only works once the project is deployed, not in the live preview.

#The client

import { coduck } from '@coduck/sdk';

const meta = await coduck.meta();
// → { projectId, projectName, deploymentSubdomain, deploymentStatus, apiKeyPrefix }

import { coduck } from '@coduck/sdk';

const meta = await coduck.meta();
// → { projectId, projectName, deploymentSubdomain, deploymentStatus, apiKeyPrefix }

Or construct one explicitly (tests, scripts, non-Next runtimes):

import { CoDuck } from '@coduck/sdk';

const c = new CoDuck({
  apiKey: process.env.CODUCK_API_KEY,
  apiUrl: 'https://api.coduck.ai/sdk',
  projectId: process.env.CODUCK_PROJECT_ID,
});

import { CoDuck } from '@coduck/sdk';

const c = new CoDuck({
  apiKey: process.env.CODUCK_API_KEY,
  apiUrl: 'https://api.coduck.ai/sdk',
  projectId: process.env.CODUCK_PROJECT_ID,
});

#Modules

Import	What it does
`@coduck/sdk/server`	Cookie-based auth for Next.js server code
`@coduck/sdk/client`	`useUser()` React hook
`@coduck/sdk/auth`	Low-level auth client (tokens)
`@coduck/sdk/forms`	Capture + read form submissions
`@coduck/sdk/storage`	Per-project file storage
`@coduck/sdk/analytics`	Custom event tracking

#Errors

SDK calls throw CoDuckError (with a code) on failure — e.g. NO_API_KEY, NO_AUTH_KEY, NO_PROJECT_ID, or HTTP_<status>:

import { CoDuckError } from '@coduck/sdk';

try {
  await coduck.meta();
} catch (err) {
  if (err instanceof CoDuckError) console.error(err.code, err.message);
}

import { CoDuckError } from '@coduck/sdk';

try {
  await coduck.meta();
} catch (err) {
  if (err instanceof CoDuckError) console.error(err.code, err.message);
}

View raw markdown →Suggest an edit