@contismo/sdk 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+        working-directory: .
+
+      - run: pnpm typecheck
+        working-directory: .
+
+      - run: pnpm lint
+        working-directory: .
+
+      - run: pnpm test
+        working-directory: .
+
+      - run: pnpm build
+        working-directory: .

package/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: ${{ github.workflow }}-release
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm build
+
+      - name: Publish to npm
+        run: pnpm --filter @contismo/sdk publish --no-git-checks --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,28 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, commits, code, and other contributions that are not aligned to this Code of Conduct.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thank you for contributing to the Contismo SDK.
+
+## Setup
+
+Requirements: Node.js 20+, pnpm 9.
+
+```bash
+pnpm install
+```
+
+## Commands
+
+| Command | Description |
+| ------- | ----------- |
+| `pnpm test` | Run unit tests |
+| `pnpm build` | Build `@contismo/sdk` |
+| `pnpm typecheck` | Typecheck the TypeScript client |
+| `pnpm lint` | Lint the TypeScript client |
+
+## Releases
+
+Bump the version in `clients/typescript/package.json`, tag the commit (e.g. `v0.1.0`), and push the tag. The release workflow publishes `@contismo/sdk` to npm.
+
+## Pull requests
+
+- Keep changes focused and well-tested.
+- Match existing code style (`pnpm lint`).
+- Update documentation when changing public API behavior.
+
+## Live API tests
+
+Optional integration tests against a real Contismo project are not run in CI. To test locally, construct a `ContismoClient` with your own endpoint, environment, and API key in a scratch script or test — do not commit secrets.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contismo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# Contismo SDK
+
+Official client libraries for the [Contismo](https://contismo.com) GraphQL Content API.
+
+## TypeScript
+
+Install:
+
+```bash
+pnpm add @contismo/sdk
+```
+
+Quick start (with `contismo.config.ts` in your project root):
+
+```typescript
+import { ContismoClient } from "@contismo/sdk";
+
+const client = new ContismoClient();
+
+const posts = await client.fetch("BlogPost", {
+  select: { _id: true, title: true },
+  limit: 10,
+});
+```
+
+Use `new ContismoClient({ config: "./path/to/contismo.config.ts" })` when the config file is elsewhere, or `{ cwd: "…" }` when the process cwd differs. Credentials and codegen paths come from the config file; the generated model registry is loaded automatically.
+
+For explicit credentials without a config file:
+
+```typescript
+const client = new ContismoClient({
+  apiKey: "gql_…",
+  endpoint: "https://graphql.contismo.com",
+  project: "your-project-id",
+  environment: "production",
+});
+```
+
+### API keys
+
+| Key prefix | Access                                |
+| ---------- | ------------------------------------- |
+| `gql_`     | Queries and introspection only        |
+| `gqlw_`    | Queries, mutations, and introspection |
+
+Pass the key as `apiKey` in the client constructor with `Authorization: Bearer` applied automatically.
+
+### Required configuration
+
+| Option        | Description                                           |
+| ------------- | ----------------------------------------------------- |
+| `apiKey`      | GraphQL API key from Studio (**Settings → API keys**) |
+| `endpoint`    | GraphQL URL (`https://graphql.contismo.com`)          |
+| `project`     | Project ID from Studio (sent as `X-Project-Id`)       |
+| `environment` | Environment apiId (sent as `X-Environment`)           |
+
+### Mutations
+
+Use a read/write key (`gqlw_…`) and `client.mutate()`:
+
+```typescript
+const client = new ContismoClient({
+  apiKey: "gqlw_…",
+  endpoint: "https://graphql.contismo.com",
+  project: "your-project-id",
+  environment: "production",
+});
+
+await client.mutate(
+  `
+  mutation CreatePost($input: BlogPostCreateInput!) {
+    createBlogPost(input: $input) { _id }
+  }
+`,
+  { input: { title: "Hello" } },
+);
+```
+
+### Generate types
+
+Add `contismo.config.ts`:
+
+```typescript
+import { defineConfig } from "@contismo/sdk/config";
+
+export default defineConfig({
+  client: {
+    apiKey: "gql_…",
+    endpoint: "https://graphql.contismo.com",
+    project: "your-project-id",
+    environment: "production",
+  },
+});
+```
+
+Run:
+
+```bash
+pnpm contismo generate
+```
+
+Writes `contismo/schema.json`, `src/generated/contismo.ts`, and `contismo-models.ts` by default (`schemaDir`, `outputDir`, and file names are configurable). See [clients/typescript/docs/codegen.md](clients/typescript/docs/codegen.md) for options.
+
+### Select-based reads
+
+After `contismo generate`, use `fetch` / `fetchOne` with a Prisma-style `select` — no hand-written query:
+
+```typescript
+import type { Entry_BlogPost } from "./generated/contismo";
+
+const client = new ContismoClient();
+
+const posts = await client.fetch<Entry_BlogPost>("BlogPost", {
+  select: {
+    _id: true,
+    title: true,
+    author: { name: true },
+  },
+  limit: 10,
+});
+
+const post = await client.fetchOne<Entry_BlogPost>("BlogPost", {
+  id: "…",
+  select: { _id: true, title: true },
+});
+```
+
+The first argument is the content model API id (`"BlogPost"`, `"Test"`, …). Nested objects in `select` become nested GraphQL selections; `true` marks a scalar leaf.
+
+### Introspection
+
+```typescript
+const schema = await client.introspect();
+```
+
+### Errors
+
+```typescript
+import { ContismoClient, isContismoError, ContismoGraphQLError } from "@contismo/sdk";
+
+try {
+  await client.query(`query { blogPost(id: "missing") { _id } }`);
+} catch (error) {
+  if (isContismoError(error) && error instanceof ContismoGraphQLError) {
+    console.error(error.code, error.message);
+  }
+}
+```
+
+## Other languages
+
+Additional clients will live under `clients/<language>/` when available.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/clients/typescript/docs/codegen.md

@@ -0,0 +1,107 @@
+# TypeScript types from your schema
+
+## Quick path: `contismo generate`
+
+1. Create `contismo.config.ts` in your project root:
+
+```typescript
+import { defineConfig } from "@contismo/sdk/config";
+
+export default defineConfig({
+  client: {
+    apiKey: "gql_…",
+    endpoint: "https://graphql.contismo.com",
+    project: "your-project-id",
+    environment: "production",
+  },
+  codegen: {
+    outputDir: "./src/generated",
+    outputFile: "contismo.ts",
+    schemaDir: "./contismo",
+    // Or full paths: schema: "./contismo/schema.json", output: "./src/generated/contismo.ts"
+    // documents: ["src/**/*.graphql"], // optional: typed operations
+  },
+});
+```
+
+2. Add a script (optional):
+
+```json
+{
+  "scripts": {
+    "generate": "contismo generate"
+  }
+}
+```
+
+3. Run:
+
+```bash
+pnpm generate
+```
+
+This pulls your live GraphQL schema and generates TypeScript types from it, similar to `prisma generate`.
+
+Generated entry types use readable fields (`string | null`, `EntryStatus | null`) instead of `Maybe<Scalars['DateTime']['output']>`. Set `codegen.prettify: false` to keep raw graphql-codegen output.
+
+## Manual workflow
+
+### Fetch the schema
+
+```typescript
+import { ContismoClient, writeIntrospectionResult } from "@contismo/sdk";
+
+const client = new ContismoClient({
+  apiKey: "gql_…",
+  endpoint: "https://graphql.contismo.com",
+  project: "your-project-id",
+  environment: "production",
+});
+
+const schema = await client.introspect();
+await writeIntrospectionResult(schema, "./contismo/schema.json");
+```
+
+### Configure codegen yourself
+
+See [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) docs if you prefer a custom `codegen.ts`.
+
+### Select-based reads (no hand-written query)
+
+`contismo generate` writes `contismo-models.ts`. `new ContismoClient()` reads `contismo.config.*` and loads that registry automatically (paths follow your `codegen` settings).
+
+```typescript
+import { ContismoClient } from "@contismo/sdk";
+import type { Entry_BlogPost } from "./generated/contismo";
+
+const client = new ContismoClient();
+// Custom config path: new ContismoClient({ config: "./config/contismo.config.ts" });
+
+const posts = await client.fetch<Entry_BlogPost>("BlogPost", {
+  select: {
+    _id: true,
+    title: true,
+    author: { name: true, avatar: { url: true } },
+  },
+  limit: 10,
+});
+
+const post = await client.fetchOne<Entry_BlogPost>("BlogPost", {
+  id: "…",
+  select: { _id: true, title: true },
+});
+```
+
+Use the content model **API id** (e.g. `"BlogPost"`, `"Test"`) as the first argument. Nested `select` objects mirror GraphQL field selection (`true` = scalar leaf, nested object = sub-selection).
+
+### Raw GraphQL (optional)
+
+```typescript
+import type { Query } from "./generated/contismo";
+
+const data = await client.query<Pick<Query, "blogPosts">>(`
+  query { blogPosts { _id title } }
+`);
+```
+
+When using `documents` in config, you can use `TypedDocumentNode` outputs with `client.query` / `client.mutate` as usual.

package/clients/typescript/eslint.config.js

@@ -0,0 +1,18 @@
+import eslint from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    ignores: ["dist/**"],
+  },
+);

package/clients/typescript/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@contismo/ts-client",
+  "version": "0.1.0",
+  "description": "Official TypeScript client for the Contismo GraphQL Content Delivery API",
+  "license": "MIT",
+  "author": "Contismo",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contismo/cms-sdk.git",
+    "directory": "clients/typescript"
+  },
+  "homepage": "https://github.com/contismo/cms-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/contismo/cms-sdk/issues"
+  },
+  "keywords": [
+    "contismo",
+    "cms",
+    "graphql",
+    "headless-cms",
+    "content-delivery"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "contismo": "./dist/cli/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./config": {
+      "import": {
+        "types": "./dist/config.d.ts",
+        "default": "./dist/config.js"
+      },
+      "require": {
+        "types": "./dist/config.d.cts",
+        "default": "./dist/config.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@graphql-codegen/cli": "^5.0.3",
+    "@graphql-codegen/typescript": "^4.1.2",
+    "@graphql-codegen/typescript-operations": "^4.4.0",
+    "@graphql-codegen/typed-document-node": "^5.0.4",
+    "jiti": "^2.4.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.16.0",
+    "@types/node": "^22.10.1",
+    "eslint": "^9.16.0",
+    "globals": "^15.13.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^2.1.8"
+  }
+}

package/clients/typescript/src/api-keys.ts

@@ -0,0 +1,13 @@
+/** Read-only GraphQL API key prefix (`gql_`). */
+export const READ_ONLY_API_KEY_PREFIX = "gql_" as const;
+
+/** Read/write GraphQL API key prefix (`gqlw_`). */
+export const READ_WRITE_API_KEY_PREFIX = "gqlw_" as const;
+
+export function isReadOnlyApiKey(apiKey: string): boolean {
+  return apiKey.startsWith(READ_ONLY_API_KEY_PREFIX) && !apiKey.startsWith(READ_WRITE_API_KEY_PREFIX);
+}
+
+export function isReadWriteApiKey(apiKey: string): boolean {
+  return apiKey.startsWith(READ_WRITE_API_KEY_PREFIX);
+}

package/clients/typescript/src/cli/codegen-typescript-config.ts

@@ -0,0 +1,36 @@
+import type { ContismoCodegenConfig } from "../config";
+
+/** Default `@graphql-codegen/typescript` options for readable Contismo types. */
+export const DEFAULT_TYPESCRIPT_CODEGEN_CONFIG = {
+  preResolveTypes: true,
+  skipTypename: true,
+  enumsAsTypes: true,
+  useTypeImports: true,
+  strictScalars: true,
+  defaultScalarType: "string",
+  maybeValue: "T | null",
+  scalars: {
+    ID: "string",
+    String: "string",
+    Boolean: "boolean",
+    Int: "number",
+    Float: "number",
+    DateTime: "string",
+    Date: "string",
+    JSON: "unknown",
+    Time: "string",
+  },
+} as const satisfies Record<string, unknown>;
+
+export function buildTypescriptCodegenConfig(
+  codegen?: ContismoCodegenConfig,
+): Record<string, unknown> {
+  return {
+    ...DEFAULT_TYPESCRIPT_CODEGEN_CONFIG,
+    ...codegen?.typescript,
+    scalars: {
+      ...DEFAULT_TYPESCRIPT_CODEGEN_CONFIG.scalars,
+      ...codegen?.typescript?.scalars,
+    },
+  };
+}

package/clients/typescript/src/cli/generate-models.ts

@@ -0,0 +1,94 @@
+import { writeFile } from "node:fs/promises";
+import type { IntrospectionQueryResult, IntrospectionType, IntrospectionTypeRef } from "../introspection";
+import type { ModelRegistry } from "../models";
+
+function unwrapNamedType(ref: IntrospectionTypeRef): { name: string; isList: boolean } | null {
+  let current: IntrospectionTypeRef | null | undefined = ref;
+  let isList = false;
+
+  while (current) {
+    if (current.kind === "LIST") {
+      isList = true;
+      current = current.ofType;
+    } else if (current.kind === "NON_NULL") {
+      current = current.ofType;
+    } else if (current.name) {
+      return { name: current.name, isList };
+    } else {
+      break;
+    }
+  }
+
+  return null;
+}
+
+export function buildModelRegistry(introspection: IntrospectionQueryResult): ModelRegistry {
+  const queryType = introspection.__schema.types.find((t) => t.name === "Query");
+  if (!queryType?.fields) {
+    return {};
+  }
+
+  const byGraphqlType = new Map<
+    string,
+    { singular?: string; plural?: string; whereInput?: string }
+  >();
+
+  for (const field of queryType.fields) {
+    const unwrapped = unwrapNamedType(field.type);
+    if (!unwrapped?.name.startsWith("Entry_")) {
+      continue;
+    }
+
+    const graphqlType = unwrapped.name;
+    const existing = byGraphqlType.get(graphqlType) ?? {};
+
+    if (unwrapped.isList) {
+      existing.plural = field.name;
+      const whereArg = field.args?.find((arg) => arg.name === "where");
+      const whereType = whereArg ? unwrapNamedType(whereArg.type)?.name : undefined;
+      if (whereType) {
+        existing.whereInput = whereType;
+      }
+    } else {
+      existing.singular = field.name;
+    }
+
+    byGraphqlType.set(graphqlType, existing);
+  }
+
+  const registry: ModelRegistry = {};
+
+  for (const [graphqlType, fields] of byGraphqlType) {
+    const singular = fields.singular ?? fields.plural;
+    const plural = fields.plural ?? fields.singular;
+    if (!singular || !plural) {
+      continue;
+    }
+
+    const isSingleton = fields.plural === undefined;
+
+    registry[graphqlType.slice("Entry_".length)] = {
+      apiId: graphqlType.slice("Entry_".length),
+      singular,
+      plural,
+      graphqlType,
+      ...(isSingleton ? { isSingleton: true } : {}),
+      ...(fields.whereInput ? { whereInput: fields.whereInput } : {}),
+    };
+  }
+
+  return registry;
+}
+
+export async function writeModelsModule(registry: ModelRegistry, filePath: string): Promise<void> {
+  const content = `/* eslint-disable */
+/** Generated by \`contismo generate\` — do not edit manually. */
+import type { ModelRegistry } from "@contismo/sdk";
+
+export const contismoModels = ${JSON.stringify(registry, null, 2)} as const satisfies ModelRegistry;
+
+export type ContismoModelName = keyof typeof contismoModels;
+`;
+
+  await writeFile(filePath, content, "utf8");
+}