@contismo/sdk 0.1.0

package/clients/typescript/tests/client.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it, vi, type Mock } from "vitest";
+import {
+  ContismoClient,
+  ContismoErrorCodes,
+  ContismoGraphQLError,
+  ContismoHttpError,
+  isContismoError,
+} from "../src/index";
+
+const config = {
+  apiKey: "gql_test_key",
+  endpoint: "https://graphql.example.com",
+  project: "proj_abc123",
+  environment: "production",
+};
+
+function mockFetch(response: Response): Mock<typeof fetch> {
+  return vi.fn<typeof fetch>().mockResolvedValue(response);
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("ContismoClient", () => {
+  it("sends correct headers on query", async () => {
+    const fetch = mockFetch(
+      jsonResponse({ data: { blogPostCollection: { items: [] } } }),
+    );
+
+    const client = new ContismoClient({ ...config, fetch });
+    await client.query(`query { blogPostCollection { items { _id } } }`);
+
+    expect(fetch).toHaveBeenCalledOnce();
+    const call = fetch.mock.calls[0];
+    const init = call?.[1];
+    if (!init) throw new Error("expected fetch to be called");
+    const headers = new Headers(init.headers);
+
+    expect(headers.get("Authorization")).toBe("Bearer gql_test_key");
+    expect(headers.get("X-Project-Id")).toBe("proj_abc123");
+    expect(headers.get("X-Environment")).toBe("production");
+    expect(headers.get("Content-Type")).toBe("application/json");
+  });
+
+  it("returns query data", async () => {
+    const fetch = mockFetch(
+      jsonResponse({
+        data: { blogPost: { _id: "1", title: "Hello" } },
+      }),
+    );
+
+    const client = new ContismoClient({ ...config, fetch });
+    const data = await client.query<{ blogPost: { _id: string; title: string } }>(
+      `query { blogPost(id: "1") { _id title } }`,
+    );
+
+    expect(data.blogPost).toEqual({ _id: "1", title: "Hello" });
+  });
+
+  it("throws ContismoGraphQLError on GraphQL errors", async () => {
+    const fetch = mockFetch(
+      jsonResponse({
+        errors: [{ message: "Not found", extensions: { code: "NOT_FOUND" } }],
+      }),
+    );
+
+    const client = new ContismoClient({ ...config, fetch });
+
+    await expect(client.query(`query { blogPost(id: "x") { _id } }`)).rejects.toMatchObject({
+      name: "ContismoGraphQLError",
+      code: "NOT_FOUND",
+    });
+  });
+
+  it("parses entry edit lock extensions", async () => {
+    const fetch = mockFetch(
+      jsonResponse({
+        errors: [
+          {
+            message: "Entry is locked",
+            extensions: {
+              code: "ENTRY_EDIT_LOCK_CONFLICT",
+              lockedByUserId: "user-1",
+              lockedByName: "Alex",
+            },
+          },
+        ],
+      }),
+    );
+
+    const client = new ContismoClient({ ...config, fetch });
+
+    try {
+      await client.query(`mutation { updateBlogPost { _id } }`);
+      expect.fail("should throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ContismoGraphQLError);
+      const gqlError = error as ContismoGraphQLError;
+      expect(gqlError.code).toBe("ENTRY_EDIT_LOCK_CONFLICT");
+      expect(gqlError.lockedByUserId).toBe("user-1");
+      expect(gqlError.lockedByName).toBe("Alex");
+      expect(isContismoError(error)).toBe(true);
+    }
+  });
+
+  it("throws ContismoHttpError on HTTP 429 without GraphQL body", async () => {
+    const fetch = mockFetch(jsonResponse({ message: "rate limited" }, 429));
+
+    const client = new ContismoClient({ ...config, fetch });
+
+    await expect(client.query(`query { blogPostCollection { items { _id } } }`)).rejects.toBeInstanceOf(
+      ContismoHttpError,
+    );
+  });
+
+  it("throws on rate limit GraphQL error shape", async () => {
+    const fetch = mockFetch(
+      jsonResponse(
+        {
+          errors: [
+            {
+              message: "Monthly API call limit exceeded",
+              extensions: { code: "RATE_LIMIT_EXCEEDED" },
+            },
+          ],
+        },
+        429,
+      ),
+    );
+
+    const client = new ContismoClient({ ...config, fetch });
+
+    await expect(client.query(`query { blogPostCollection { items { _id } } }`)).rejects.toMatchObject({
+      code: ContismoErrorCodes.RATE_LIMIT_EXCEEDED,
+    });
+  });
+
+  it("blocks mutate for read-only keys before fetch", async () => {
+    const fetch = mockFetch(jsonResponse({ data: { ok: true } }));
+    const client = new ContismoClient({ ...config, fetch });
+
+    try {
+      await client.mutate(`mutation { createBlogPost(input: {}) { _id } }`);
+      expect.fail("should throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ContismoGraphQLError);
+      expect((error as ContismoGraphQLError).code).toBe(ContismoErrorCodes.FORBIDDEN);
+    }
+
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("allows mutate for read-write keys", async () => {
+    const fetch = mockFetch(
+      jsonResponse({ data: { createBlogPost: { _id: "new" } } }),
+    );
+    const client = new ContismoClient({
+      ...config,
+      apiKey: "gqlw_test_key",
+      fetch,
+    });
+
+    const data = await client.mutate<{ createBlogPost: { _id: string } }>(
+      `mutation { createBlogPost(input: {}) { _id } }`,
+    );
+
+    expect(data.createBlogPost._id).toBe("new");
+  });
+
+  it("runs introspection with operation name", async () => {
+    const fetch = mockFetch(
+      jsonResponse({
+        data: {
+          __schema: {
+            queryType: { name: "Query" },
+            mutationType: { name: "Mutation" },
+            subscriptionType: null,
+            types: [],
+            directives: [],
+          },
+        },
+      }),
+    );
+
+    const client = new ContismoClient({ ...config, fetch });
+    const result = await client.introspect();
+
+    expect(result.__schema.queryType?.name).toBe("Query");
+
+    const call = fetch.mock.calls[0];
+    const init = call?.[1];
+    if (!init?.body) throw new Error("expected fetch to be called");
+    const body = JSON.parse(init.body as string) as {
+      operationName: string;
+      query: string;
+    };
+    expect(body.operationName).toBe("IntrospectionQuery");
+    expect(body.query).toContain("query IntrospectionQuery");
+  });
+
+  it("forwards AbortSignal", async () => {
+    const fetch = mockFetch(
+      jsonResponse({ data: { blogPostCollection: { items: [] } } }),
+    );
+    const client = new ContismoClient({ ...config, fetch });
+    const controller = new AbortController();
+
+    await client.query(`query { blogPostCollection { items { _id } } }`, undefined, {
+      signal: controller.signal,
+    });
+
+    const call = fetch.mock.calls[0];
+    const init = call?.[1];
+    if (!init) throw new Error("expected fetch to be called");
+    expect(init.signal).toBe(controller.signal);
+  });
+});

package/clients/typescript/tests/load-client.test.ts

@@ -0,0 +1,126 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { rm } from "node:fs/promises";
+import { describe, expect, it, vi, type Mock } from "vitest";
+import { ContismoClient } from "../src/client";
+
+function mockFetch(response: Response): Mock<typeof fetch> {
+  return vi.fn<typeof fetch>().mockResolvedValue(response);
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("ContismoClient config discovery", () => {
+  it("loads config and model registry from default locations", async () => {
+    const dir = join(tmpdir(), `contismo-load-${Date.now()}`);
+    await mkdir(join(dir, "src/generated"), { recursive: true });
+
+    try {
+      await writeFile(
+        join(dir, "contismo.config.json"),
+        JSON.stringify({
+          client: {
+            apiKey: "gql_test",
+            endpoint: "https://graphql.contismo.com",
+            project: "proj_1",
+            environment: "production",
+          },
+          codegen: {
+            outputDir: "./src/generated",
+          },
+        }),
+      );
+
+      await writeFile(
+        join(dir, "src/generated/contismo-models.ts"),
+        `export const contismoModels = {
+  Test: {
+    apiId: "Test",
+    singular: "test",
+    plural: "tests",
+    graphqlType: "Entry_Test",
+  },
+};`,
+      );
+
+      const fetch = mockFetch(jsonResponse({ data: { tests: [{ _id: "1" }] } }));
+      const client = new ContismoClient({ cwd: dir, fetch });
+      const rows = await client.fetch("Test", { select: { _id: true } });
+
+      expect(rows).toEqual([{ _id: "1" }]);
+      expect(fetch).toHaveBeenCalledOnce();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("loads config from a custom path", async () => {
+    const dir = join(tmpdir(), `contismo-load-custom-${Date.now()}`);
+    await mkdir(join(dir, "cfg/generated"), { recursive: true });
+
+    try {
+      await writeFile(
+        join(dir, "cfg/app.config.json"),
+        JSON.stringify({
+          client: {
+            apiKey: "gql_test",
+            endpoint: "https://graphql.contismo.com",
+            project: "proj_2",
+            environment: "staging",
+          },
+          codegen: {
+            output: "./cfg/generated/types.ts",
+            models: "./cfg/generated/registry.mjs",
+          },
+        }),
+      );
+
+      await writeFile(
+        join(dir, "cfg/generated/registry.mjs"),
+        `export const contismoModels = {
+  Blog: { apiId: "Blog", singular: "blog", plural: "blogs", graphqlType: "Entry_Blog" },
+};`,
+      );
+
+      const fetch = mockFetch(jsonResponse({ data: { blogs: [] } }));
+      const client = new ContismoClient({
+        cwd: dir,
+        config: "./cfg/app.config.json",
+        fetch,
+      });
+
+      await expect(client.fetch("Blog", { select: { _id: true } })).resolves.toEqual([]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws when the model registry file is missing", async () => {
+    const dir = join(tmpdir(), `contismo-load-missing-${Date.now()}`);
+    await mkdir(dir, { recursive: true });
+
+    try {
+      await writeFile(
+        join(dir, "contismo.config.json"),
+        JSON.stringify({
+          client: {
+            apiKey: "gql_test",
+            endpoint: "https://graphql.contismo.com",
+            project: "proj_1",
+            environment: "production",
+          },
+        }),
+      );
+
+      expect(() => new ContismoClient({ cwd: dir })).toThrow(/Model registry not found/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/clients/typescript/tests/load-config.test.ts

@@ -0,0 +1,32 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { rm } from "node:fs/promises";
+import { describe, expect, it } from "vitest";
+import { loadContismoConfig } from "../src/load-config";
+
+describe("loadContismoConfig", () => {
+  it("loads contismo.config.json", async () => {
+    const dir = join(tmpdir(), `contismo-config-${Date.now()}`);
+    await mkdir(dir, { recursive: true });
+
+    try {
+      await writeFile(
+        join(dir, "contismo.config.json"),
+        JSON.stringify({
+          client: {
+            apiKey: "gql_test",
+            endpoint: "https://graphql.contismo.com",
+            project: "proj_1",
+            environment: "production",
+          },
+        }),
+      );
+
+      const config = loadContismoConfig(dir);
+      expect(config.client.project).toBe("proj_1");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/clients/typescript/tests/prettify-generated-types.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { prettifyGeneratedTypes } from "../src/cli/prettify-generated-types";
+
+describe("prettifyGeneratedTypes", () => {
+  it("inlines output scalars and Maybe wrappers without breaking utility types", () => {
+    const input = `
+export type Maybe<T> = T | null;
+export type InputMaybe<T> = T | null;
+export type Scalars = {
+  DateTime: { input: string; output: string; }
+  String: { input: string; output: string; }
+};
+
+export type Entry_Test = {
+  _id: Scalars['ID']['output'];
+  tit?: Maybe<Scalars['String']['output']>;
+  _updatedAt?: Maybe<Scalars['DateTime']['output']>;
+  content?: Maybe<RichText>;
+};
+`;
+
+    const out = prettifyGeneratedTypes(input);
+
+    expect(out).toContain("_id: string;");
+    expect(out).toContain("tit?: string | null;");
+    expect(out).toContain("_updatedAt?: string | null;");
+    expect(out).toContain("content?: RichText | null;");
+    expect(out).not.toContain("Scalars[");
+    expect(out).not.toContain("Maybe<");
+    expect(out).not.toContain("export type T | null");
+    expect(out).not.toContain("export type MakeT");
+  });
+
+  it("leaves export type alias lines untouched before stripping boilerplate", () => {
+    const input = `
+export type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> };
+export type Entry_Test = { tit?: Maybe<Scalars['String']['output']>; };
+`;
+    const out = prettifyGeneratedTypes(input);
+    expect(out).toContain("tit?: string | null;");
+    expect(out).not.toContain("MakeMaybe");
+  });
+});

package/clients/typescript/tests/resolve-codegen-paths.test.ts

@@ -0,0 +1,57 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveCodegenPaths } from "../src/resolve-codegen-paths";
+
+describe("resolveCodegenPaths", () => {
+  const cwd = "/app";
+
+  it("uses defaults", () => {
+    expect(resolveCodegenPaths(cwd)).toEqual({
+      schemaPath: join(cwd, "contismo/schema.json"),
+      outputPath: join(cwd, "src/generated/contismo.ts"),
+      modelsPath: join(cwd, "src/generated/contismo-models.ts"),
+    });
+  });
+
+  it("uses outputDir and schemaDir", () => {
+    expect(
+      resolveCodegenPaths(cwd, {
+        outputDir: "./lib/contismo",
+        outputFile: "types.ts",
+        schemaDir: "./.contismo",
+        schemaFile: "introspection.json",
+      }),
+    ).toEqual({
+      schemaPath: join(cwd, ".contismo/introspection.json"),
+      outputPath: join(cwd, "lib/contismo/types.ts"),
+      modelsPath: join(cwd, "lib/contismo/contismo-models.ts"),
+    });
+  });
+
+  it("prefers full paths when set", () => {
+    expect(
+      resolveCodegenPaths(cwd, {
+        outputDir: "./ignored",
+        output: "./custom/out.ts",
+        schemaDir: "./ignored",
+        schema: "./custom/schema.json",
+      }),
+    ).toEqual({
+      schemaPath: join(cwd, "custom/schema.json"),
+      outputPath: join(cwd, "custom/out.ts"),
+      modelsPath: join(cwd, "custom/contismo-models.ts"),
+    });
+  });
+
+  it("places models next to a custom output file", () => {
+    expect(
+      resolveCodegenPaths(cwd, {
+        output: "./custom/out.ts",
+      }),
+    ).toEqual({
+      schemaPath: join(cwd, "contismo/schema.json"),
+      outputPath: join(cwd, "custom/out.ts"),
+      modelsPath: join(cwd, "custom/contismo-models.ts"),
+    });
+  });
+});

package/clients/typescript/tests/select.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { buildSelectionSet } from "../src/select";
+import { buildFetchListQuery, buildFetchOneQuery } from "../src/fetch-query";
+import type { ModelRegistryEntry } from "../src/models";
+
+const testModel: ModelRegistryEntry = {
+  apiId: "Test",
+  singular: "test",
+  plural: "tests",
+  graphqlType: "Entry_Test",
+  whereInput: "Entry_Test_WhereInput",
+};
+
+describe("buildSelectionSet", () => {
+  it("builds flat and nested fields", () => {
+    expect(
+      buildSelectionSet({
+        _id: true,
+        tit: true,
+        content: { asHtml: true },
+      }),
+    ).toBe("_id tit content { asHtml }");
+  });
+});
+
+describe("buildFetchListQuery", () => {
+  it("builds a collection query with variables", () => {
+    const built = buildFetchListQuery(testModel, {
+      select: { _id: true, tit: true },
+      limit: 10,
+    });
+
+    expect(built.operationName).toBe("FetchTestList");
+    expect(built.resultKey).toBe("tests");
+    expect(built.query).toContain("tests(limit: $limit)");
+    expect(built.query).toContain("_id tit");
+    expect(built.variables).toEqual({ limit: 10 });
+  });
+});
+
+describe("buildFetchOneQuery", () => {
+  it("builds a singular query", () => {
+    const built = buildFetchOneQuery(testModel, {
+      select: { _id: true },
+      id: "entry-1",
+    });
+
+    expect(built.operationName).toBe("FetchTestOne");
+    expect(built.resultKey).toBe("test");
+    expect(built.query).toContain("test(id: $id)");
+    expect(built.variables).toEqual({ id: "entry-1" });
+  });
+});

package/clients/typescript/tests/write-introspection.test.ts

@@ -0,0 +1,30 @@
+import { readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { writeIntrospectionResult } from "../src/write-introspection";
+import type { IntrospectionQueryResult } from "../src/introspection";
+
+describe("writeIntrospectionResult", () => {
+  it("writes schema JSON for codegen", async () => {
+    const filePath = join(tmpdir(), `contismo-introspection-${Date.now()}.json`);
+    const result: IntrospectionQueryResult = {
+      __schema: {
+        queryType: { name: "Query" },
+        mutationType: null,
+        subscriptionType: null,
+        types: [],
+        directives: [],
+      },
+    };
+
+    try {
+      await writeIntrospectionResult(result, filePath);
+      const raw = await readFile(filePath, "utf8");
+      const parsed = JSON.parse(raw) as { data: IntrospectionQueryResult };
+      expect(parsed.data.__schema.queryType?.name).toBe("Query");
+    } finally {
+      await rm(filePath, { force: true });
+    }
+  });
+});

package/clients/typescript/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  },
+  "include": ["src", "tests"]
+}

package/clients/typescript/tsup.config.ts

@@ -0,0 +1,32 @@
+import { defineConfig } from "tsup";
+
+const shared = {
+  sourcemap: true,
+  clean: true,
+  splitting: false,
+  treeshake: true,
+} as const;
+
+export default defineConfig([
+  {
+    ...shared,
+    entry: {
+      index: "src/index.ts",
+      config: "src/config.ts",
+    },
+    format: ["esm", "cjs"],
+    dts: true,
+  },
+  {
+    ...shared,
+    clean: false,
+    entry: {
+      "cli/main": "src/cli/main.ts",
+    },
+    format: ["esm"],
+    dts: false,
+    banner: {
+      js: "#!/usr/bin/env node",
+    },
+  },
+]);

package/clients/typescript/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    pool: "forks",
+  },
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@contismo/sdk",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@9.0.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "pnpm --filter @contismo/ts-client build",
+    "test": "pnpm --filter @contismo/ts-client test",
+    "lint": "pnpm --filter @contismo/ts-client lint",
+    "typecheck": "pnpm --filter @contismo/ts-client typecheck"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "clients/typescript"