@contismo/sdk 0.1.0

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

@@ -0,0 +1,44 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ContismoClient } from "../client";
+import { resolveCodegenPaths } from "../resolve-codegen-paths";
+import { writeIntrospectionResult } from "../write-introspection";
+import { loadContismoConfig } from "./load-config";
+import { buildModelRegistry, writeModelsModule } from "./generate-models";
+import { prettifyGeneratedTypes } from "./prettify-generated-types";
+import { runGraphQLCodegen } from "./run-codegen";
+
+export type GenerateOptions = {
+  cwd?: string;
+  config?: string;
+};
+
+export async function runGenerate(options: GenerateOptions = {}): Promise<void> {
+  const cwd = options.cwd ?? process.cwd();
+  const config = loadContismoConfig(cwd, options.config);
+
+  const { schemaPath, outputPath, modelsPath } = resolveCodegenPaths(cwd, config.codegen);
+
+  console.log("Introspecting schema…");
+  const client = new ContismoClient(config.client);
+  const introspection = await client.introspect();
+
+  await mkdir(dirname(schemaPath), { recursive: true });
+  await writeIntrospectionResult(introspection, schemaPath);
+  console.log(`Wrote ${schemaPath}`);
+
+  console.log("Generating types…");
+  await runGraphQLCodegen(cwd, schemaPath, outputPath, config.codegen);
+
+  if (config.codegen?.prettify !== false) {
+    const raw = await readFile(outputPath, "utf8");
+    await writeFile(outputPath, `${prettifyGeneratedTypes(raw)}\n`, "utf8");
+  }
+
+  console.log(`Wrote ${outputPath}`);
+
+  const registry = buildModelRegistry(introspection);
+  await writeModelsModule(registry, modelsPath);
+  console.log(`Wrote ${modelsPath}`);
+}

package/clients/typescript/src/cli/import-from-sdk.ts

@@ -0,0 +1,12 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const sdkRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+
+/** Resolve and import a dependency bundled with `@contismo/sdk` (works under pnpm). */
+export function importFromSdk<T = unknown>(specifier: string): Promise<T> {
+  const require = createRequire(join(sdkRoot, "package.json"));
+  const resolved = require.resolve(specifier);
+  return import(pathToFileURL(resolved).href) as Promise<T>;
+}

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

@@ -0,0 +1 @@
+export { findConfigFile, loadContismoConfig } from "../load-config";

package/clients/typescript/src/cli/main.ts

@@ -0,0 +1,39 @@
+import { parseArgs } from "node:util";
+import { runGenerate } from "./generate";
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    config: { type: "string", short: "c" },
+    help: { type: "boolean", short: "h" },
+  },
+});
+
+const command = positionals[0];
+
+if (values.help || command === "help" || command === undefined) {
+  console.log(
+    `Contismo CLI
+
+Usage:
+  contismo generate [--config <path>]   Fetch schema and generate TypeScript types
+
+Requires contismo.config.ts in your project.
+`,
+  );
+  process.exit(command === undefined ? 1 : 0);
+}
+
+if (command === "generate") {
+  try {
+    await runGenerate(values.config !== undefined ? { config: values.config } : {});
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+console.error(`Unknown command: ${command}`);
+console.error("Run contismo --help");
+process.exit(1);

package/clients/typescript/src/cli/prettify-generated-types.ts

@@ -0,0 +1,129 @@
+/** Maps GraphQL scalar names to TypeScript types used in generated output. */
+export const PRETTIFY_SCALAR_TYPES: Record<string, string> = {
+  ID: "string",
+  String: "string",
+  Boolean: "boolean",
+  Int: "number",
+  Float: "number",
+  DateTime: "string",
+  Date: "string",
+  JSON: "unknown",
+  Time: "string",
+};
+
+const BOILERPLATE_TYPES = [
+  "Maybe",
+  "InputMaybe",
+  "Exact",
+  "MakeOptional",
+  "MakeMaybe",
+  "MakeEmpty",
+  "Incremental",
+  "Scalars",
+] as const;
+
+/**
+ * Simplifies graphql-codegen output for Contismo consumers:
+ * - `Maybe<Scalars['DateTime']['output']>` → `string | null`
+ * - `Maybe<RichText>` → `RichText | null`
+ * - removes unused codegen utility types
+ */
+export function prettifyGeneratedTypes(source: string): string {
+  let output = source;
+
+  for (const [scalar, tsType] of Object.entries(PRETTIFY_SCALAR_TYPES)) {
+    const quoted = scalar.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    output = output.replace(
+      new RegExp(`Maybe<Scalars\\['${quoted}'\\]\\['output'\\]>`, "g"),
+      `${tsType} | null`,
+    );
+    output = output.replace(
+      new RegExp(`Scalars\\['${quoted}'\\]\\['output'\\]`, "g"),
+      tsType,
+    );
+    output = output.replace(
+      new RegExp(`InputMaybe<Scalars\\['${quoted}'\\]\\['input'\\]>`, "g"),
+      `${tsType} | null`,
+    );
+    output = output.replace(
+      new RegExp(`Scalars\\['${quoted}'\\]\\['input'\\]`, "g"),
+      tsType,
+    );
+  }
+
+  output = output
+    .split("\n")
+    .map((line) => {
+      if (line.startsWith("export type ")) {
+        return line;
+      }
+      return line
+        .replace(/\?: Maybe<([^>]+)>/g, "?: $1 | null")
+        .replace(/: Maybe<([^>]+)>/g, ": $1 | null")
+        .replace(/InputMaybe<([^>]+)>/g, "$1 | null");
+    })
+    .join("\n");
+
+  for (const typeName of BOILERPLATE_TYPES) {
+    output = removeExportTypeBlock(output, typeName);
+  }
+
+  output = output.replace(
+    /\/\*\* All built-in and custom scalars, mapped to their actual values \*\/\n/g,
+    "",
+  );
+
+  return output.replace(/\n{3,}/g, "\n\n").trimStart();
+}
+
+function removeExportTypeBlock(source: string, typeName: string): string {
+  const marker = `export type ${typeName}`;
+  const start = source.indexOf(marker);
+  if (start === -1) {
+    return source;
+  }
+
+  const assignIndex = source.indexOf("=", start);
+  if (assignIndex === -1) {
+    return source;
+  }
+
+  let index = assignIndex + 1;
+  while (index < source.length && /\s/.test(source[index] ?? "")) {
+    index++;
+  }
+
+  if (source[index] === "{") {
+    let depth = 0;
+    let end = index;
+    for (; end < source.length; end++) {
+      const char = source[end];
+      if (char === "{") {
+        depth++;
+      } else if (char === "}") {
+        depth--;
+        if (depth === 0) {
+          end++;
+          break;
+        }
+      }
+    }
+    if (source[end] === ";") {
+      end++;
+    }
+    if (source[end] === "\n") {
+      end++;
+    }
+    return source.slice(0, start) + source.slice(end);
+  }
+
+  const end = source.indexOf(";", assignIndex);
+  if (end === -1) {
+    return source;
+  }
+  let sliceEnd = end + 1;
+  if (source[sliceEnd] === "\n") {
+    sliceEnd++;
+  }
+  return source.slice(0, start) + source.slice(sliceEnd);
+}

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

@@ -0,0 +1,58 @@
+import { dirname } from "node:path";
+import { mkdir } from "node:fs/promises";
+import type { ContismoCodegenConfig } from "../config";
+import { buildTypescriptCodegenConfig } from "./codegen-typescript-config";
+import { importFromSdk } from "./import-from-sdk";
+
+type CodegenModule = {
+  generate: (
+    config: unknown,
+    saveToFile?: boolean,
+  ) => Promise<unknown[]>;
+};
+
+export async function runGraphQLCodegen(
+  cwd: string,
+  schemaPath: string,
+  outputPath: string,
+  codegen?: ContismoCodegenConfig,
+): Promise<void> {
+  const documents = codegen?.documents;
+  const hasDocuments = documents !== undefined && documents.length > 0;
+
+  let generate: CodegenModule["generate"];
+  try {
+    const cli = await importFromSdk<CodegenModule>("@graphql-codegen/cli");
+    generate = cli.generate;
+    await importFromSdk("@graphql-codegen/typescript");
+    if (hasDocuments) {
+      await importFromSdk("@graphql-codegen/typescript-operations");
+      await importFromSdk("@graphql-codegen/typed-document-node");
+    }
+  } catch {
+    throw new Error(
+      "Failed to load the code generator bundled with @contismo/sdk. Reinstall @contismo/sdk and try again.",
+    );
+  }
+
+  await mkdir(dirname(outputPath), { recursive: true });
+
+  const plugins = hasDocuments
+    ? ["typescript", "typescript-operations", "typed-document-node"]
+    : ["typescript"];
+
+  await generate(
+    {
+      cwd,
+      schema: schemaPath,
+      ...(hasDocuments ? { documents } : {}),
+      generates: {
+        [outputPath]: {
+          plugins,
+          config: buildTypescriptCodegenConfig(codegen),
+        },
+      },
+    },
+    true,
+  );
+}

package/clients/typescript/src/client.ts

@@ -0,0 +1,152 @@
+import { isReadOnlyApiKey } from "./api-keys";
+import { ContismoErrorCodes, ContismoGraphQLError } from "./errors";
+import { executeGraphQL } from "./execute";
+import {
+  buildFetchListQuery,
+  buildFetchOneQuery,
+  type FetchListArgs,
+  type FetchOneArgs,
+} from "./fetch-query";
+import type { ModelRegistry, ModelRegistryEntry } from "./models";
+import { buildGraphQLPayload } from "./request-payload";
+import { INTROSPECTION_QUERY, type IntrospectionQueryResult } from "./introspection";
+import { resolveContismoClientConfig, type ContismoClientOptions } from "./load-client";
+import type { ContismoClientConfig, RequestOptions } from "./types";
+
+export type { ContismoClientOptions };
+
+export type FetchOptions = FetchListArgs & RequestOptions;
+export type FetchOneOptions = FetchOneArgs & RequestOptions;
+
+export class ContismoClient {
+  private readonly config: ContismoClientConfig;
+
+  /**
+   * Pass full `apiKey`, `endpoint`, `project`, and `environment` to skip config discovery.
+   * With no credentials (or only `cwd` / `config`), loads `contismo.config.*` and the generated model registry.
+   */
+  constructor(options: ContismoClientConfig | ContismoClientOptions = {}) {
+    this.config = resolveContismoClientConfig(options);
+  }
+
+  /**
+   * Run a GraphQL query.
+   */
+  query<TData>(
+    document: string,
+    variables?: Record<string, unknown>,
+    options?: RequestOptions,
+  ): Promise<TData> {
+    return executeGraphQL<TData>(this.config, buildGraphQLPayload(document, variables), options);
+  }
+
+  /**
+   * Run a GraphQL mutation. Rejects before the network when using a read-only (`gql_`) API key.
+   */
+  mutate<TData>(
+    document: string,
+    variables?: Record<string, unknown>,
+    options?: RequestOptions,
+  ): Promise<TData> {
+    if (isReadOnlyApiKey(this.config.apiKey)) {
+      throw new ContismoGraphQLError("Read-only API keys cannot perform mutations", [
+        { message: "Read-only API keys cannot perform mutations", extensions: { code: ContismoErrorCodes.FORBIDDEN } },
+      ]);
+    }
+
+    return executeGraphQL<TData>(this.config, buildGraphQLPayload(document, variables), options);
+  }
+
+  /** Download the project GraphQL schema (used by `contismo generate` for TypeScript types). */
+  introspect(options?: RequestOptions): Promise<IntrospectionQueryResult> {
+    return executeGraphQL<IntrospectionQueryResult>(
+      this.config,
+      {
+        query: INTROSPECTION_QUERY,
+        operationName: "IntrospectionQuery",
+      },
+      { ...options, operationName: "IntrospectionQuery" },
+    );
+  }
+
+  /**
+   * Fetch all entries for a content model using a Prisma-style `select` object.
+   * Requires a model registry (loaded automatically from config unless you pass `models`).
+   */
+  async fetch<T = unknown>(model: string, options: FetchOptions): Promise<T[]> {
+    const entry = this.resolveModel(model);
+    const { signal, operationName, ...fetchArgs } = options;
+    const built = buildFetchListQuery(entry, fetchArgs);
+    const requestOptions: RequestOptions = {
+      operationName: operationName ?? built.operationName,
+    };
+    if (signal !== undefined) {
+      requestOptions.signal = signal;
+    }
+    const data = await executeGraphQL<Record<string, T[] | T | null>>(
+      this.config,
+      buildGraphQLPayload(built.query, built.variables, built.operationName),
+      requestOptions,
+    );
+
+    const result = data[built.resultKey];
+    if (entry.isSingleton) {
+      return result == null ? [] : [result as T];
+    }
+    return (result ?? []) as T[];
+  }
+
+  /**
+   * Fetch one entry by id (or unique filters) using a `select` object.
+   */
+  async fetchOne<T = unknown>(model: string, options: FetchOneOptions): Promise<T | null> {
+    const entry = this.resolveModel(model);
+    const { signal, operationName, ...fetchArgs } = options;
+    const built = buildFetchOneQuery(entry, fetchArgs);
+    const requestOptions: RequestOptions = {
+      operationName: operationName ?? built.operationName,
+    };
+    if (signal !== undefined) {
+      requestOptions.signal = signal;
+    }
+    const data = await executeGraphQL<Record<string, T | null>>(
+      this.config,
+      buildGraphQLPayload(built.query, built.variables, built.operationName),
+      requestOptions,
+    );
+
+    return data[built.resultKey] ?? null;
+  }
+
+  /**
+   * Low-level GraphQL request with full control over the document and operation name.
+   */
+  rawRequest<TData>(
+    document: string,
+    variables?: Record<string, unknown>,
+    options?: RequestOptions,
+  ): Promise<TData> {
+    return executeGraphQL<TData>(
+      this.config,
+      buildGraphQLPayload(document, variables, options?.operationName),
+      options,
+    );
+  }
+
+  private resolveModel(model: string): ModelRegistryEntry {
+    const registry = this.config.models;
+    if (!registry) {
+      throw new Error(
+        "fetch requires a model registry. Run `contismo generate`, then construct the client from config (e.g. `new ContismoClient()`).",
+      );
+    }
+
+    const entry = registry[model];
+    if (!entry) {
+      const known = Object.keys(registry).join(", ");
+      throw new Error(`Unknown model "${model}". Known models: ${known || "(none)"}`);
+    }
+
+    return entry;
+  }
+}

package/clients/typescript/src/config.ts

@@ -0,0 +1,41 @@
+import type { ContismoClientConfig } from "./types";
+
+export type ContismoCodegenConfig = {
+  /** Directory for introspection JSON. Default: `./contismo` (file: `schema.json`). */
+  schemaDir?: string;
+  /** Schema file name inside `schemaDir`. Default: `schema.json`. */
+  schemaFile?: string;
+  /** Full path to introspection JSON; overrides `schemaDir` / `schemaFile`. */
+  schema?: string;
+  /** Directory for generated TypeScript. Default: `./src/generated` (file: `contismo.ts`). */
+  outputDir?: string;
+  /** Generated file name inside `outputDir`. Default: `contismo.ts`. */
+  outputFile?: string;
+  /** Full path to generated TypeScript; overrides `outputDir` / `outputFile`. */
+  output?: string;
+  /** Model registry file name inside `outputDir`. Default: `contismo-models.ts`. */
+  modelsFile?: string;
+  /** Full path to generated model registry; default: `<outputDir>/contismo-models.ts`. */
+  models?: string;
+  /** Document globs for typed operations. Omit for schema types only. */
+  documents?: string[];
+  /**
+   * Overrides for `@graphql-codegen/typescript` (merged with Contismo defaults:
+   * inlined scalars, no `__typename`, enums as string unions).
+   */
+  typescript?: {
+    scalars?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  /** Post-process types for readable fields (`string | null` vs `Maybe<Scalars[…]>`). Default: `true`. */
+  prettify?: boolean;
+};
+
+export type ContismoConfig = {
+  client: ContismoClientConfig;
+  codegen?: ContismoCodegenConfig;
+};
+
+export function defineConfig(config: ContismoConfig): ContismoConfig {
+  return config;
+}

package/clients/typescript/src/errors.ts

@@ -0,0 +1,82 @@
+import type { GraphQLResponseError } from "./types";
+
+export const ContismoErrorCodes = {
+  NOT_FOUND: "NOT_FOUND",
+  FORBIDDEN: "FORBIDDEN",
+  CONFLICT: "CONFLICT",
+  BAD_REQUEST: "BAD_REQUEST",
+  ENTRY_EDIT_LOCK_CONFLICT: "ENTRY_EDIT_LOCK_CONFLICT",
+  PLAN_LIMIT_EXCEEDED: "PLAN_LIMIT_EXCEEDED",
+  RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED",
+  TAKEOVER_REQUEST_COOLDOWN: "TAKEOVER_REQUEST_COOLDOWN",
+  INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR",
+} as const;
+
+export type ContismoErrorCode = (typeof ContismoErrorCodes)[keyof typeof ContismoErrorCodes] | string;
+
+export class ContismoError extends Error {
+  readonly code: ContismoErrorCode;
+  readonly httpStatus?: number;
+
+  constructor(message: string, options: { code: ContismoErrorCode; httpStatus?: number }) {
+    super(message);
+    this.name = "ContismoError";
+    this.code = options.code;
+    if (options.httpStatus !== undefined) {
+      this.httpStatus = options.httpStatus;
+    }
+  }
+}
+
+export class ContismoGraphQLError extends ContismoError {
+  readonly errors: GraphQLResponseError[];
+  readonly lockedByUserId?: string;
+  readonly lockedByName?: string | null;
+  readonly limitType?: string;
+  readonly retryAfterSeconds?: number;
+
+  constructor(message: string, errors: GraphQLResponseError[], httpStatus?: number) {
+    const primary = errors[0];
+    const extensions = primary?.extensions;
+    const code = (extensions?.code as ContismoErrorCode | undefined) ?? ContismoErrorCodes.INTERNAL_SERVER_ERROR;
+
+    super(message, httpStatus === undefined ? { code } : { code, httpStatus });
+    this.name = "ContismoGraphQLError";
+    this.errors = errors;
+
+    if (typeof extensions?.lockedByUserId === "string") {
+      this.lockedByUserId = extensions.lockedByUserId;
+    }
+    if (extensions && "lockedByName" in extensions) {
+      const name = extensions.lockedByName;
+      if (name === null || typeof name === "string") {
+        this.lockedByName = name;
+      }
+    }
+    if (typeof extensions?.limitType === "string") {
+      this.limitType = extensions.limitType;
+    }
+    if (typeof extensions?.retryAfterSeconds === "number" && Number.isFinite(extensions.retryAfterSeconds)) {
+      this.retryAfterSeconds = extensions.retryAfterSeconds;
+    }
+  }
+}
+
+export class ContismoHttpError extends ContismoError {
+  readonly body: unknown;
+
+  constructor(message: string, httpStatus: number, code: ContismoErrorCode, body: unknown) {
+    super(message, { code, httpStatus });
+    this.name = "ContismoHttpError";
+    this.body = body;
+  }
+}
+
+export function isContismoError(error: unknown): error is ContismoError {
+  return error instanceof ContismoError;
+}
+
+export function parseGraphQLErrors(errors: GraphQLResponseError[], httpStatus?: number): ContismoGraphQLError {
+  const message = errors.map((e) => e.message).join("\n") || "GraphQL request failed";
+  return new ContismoGraphQLError(message, errors, httpStatus);
+}

package/clients/typescript/src/execute.ts

@@ -0,0 +1,104 @@
+import { ContismoErrorCodes, ContismoGraphQLError, ContismoHttpError, parseGraphQLErrors } from "./errors";
+import type {
+  ContismoClientConfig,
+  GraphQLRequestPayload,
+  GraphQLResponse,
+  RequestOptions,
+} from "./types";
+
+export function buildHeaders(config: ContismoClientConfig): Headers {
+  const headers = new Headers({
+    Authorization: `Bearer ${config.apiKey}`,
+    "Content-Type": "application/json",
+    "X-Project-Id": config.project,
+    "X-Environment": config.environment,
+  });
+
+  if (config.requestId) {
+    headers.set("X-Request-Id", config.requestId);
+  }
+
+  if (config.headers) {
+    for (const [key, value] of Object.entries(config.headers)) {
+      headers.set(key, value);
+    }
+  }
+
+  return headers;
+}
+
+export async function executeGraphQL<TData>(
+  config: ContismoClientConfig,
+  payload: GraphQLRequestPayload,
+  options?: RequestOptions,
+): Promise<TData> {
+  const fetchFn = config.fetch ?? globalThis.fetch;
+  const headers = buildHeaders(config);
+
+  const operationName = payload.operationName ?? options?.operationName;
+  const requestBody: Record<string, unknown> = { query: payload.query };
+  if (payload.variables !== undefined) {
+    requestBody.variables = payload.variables;
+  }
+  if (operationName !== undefined) {
+    requestBody.operationName = operationName;
+  }
+
+  const requestInit: RequestInit = {
+    method: "POST",
+    headers,
+    body: JSON.stringify(requestBody),
+  };
+  if (options?.signal !== undefined) {
+    requestInit.signal = options.signal;
+  }
+
+  const response = await fetchFn(config.endpoint, requestInit);
+
+  const httpStatus = response.status;
+  let body: unknown;
+
+  try {
+    body = await response.json();
+  } catch {
+    if (!response.ok) {
+      throw new ContismoHttpError(
+        `Request failed with status ${httpStatus}`,
+        httpStatus,
+        ContismoErrorCodes.INTERNAL_SERVER_ERROR,
+        null,
+      );
+    }
+    throw new ContismoHttpError("Invalid JSON response", httpStatus, ContismoErrorCodes.INTERNAL_SERVER_ERROR, null);
+  }
+
+  if (!response.ok) {
+    const graphqlBody = body as GraphQLResponse<TData>;
+    if (graphqlBody.errors?.length) {
+      throw parseGraphQLErrors(graphqlBody.errors, httpStatus);
+    }
+    throw new ContismoHttpError(
+      `Request failed with status ${httpStatus}`,
+      httpStatus,
+      ContismoErrorCodes.INTERNAL_SERVER_ERROR,
+      body,
+    );
+  }
+
+  const graphqlBody = body as GraphQLResponse<TData>;
+
+  if (graphqlBody.errors?.length) {
+    throw parseGraphQLErrors(graphqlBody.errors, httpStatus);
+  }
+
+  if (graphqlBody.data === undefined) {
+    throw new ContismoHttpError(
+      "GraphQL response missing data",
+      httpStatus,
+      ContismoErrorCodes.INTERNAL_SERVER_ERROR,
+      body,
+    );
+  }
+
+  return graphqlBody.data;
+}