@contismo/sdk 0.1.0

package/clients/typescript/src/fetch-query.ts

@@ -0,0 +1,123 @@
+import { buildSelectionSet, type SelectShape } from "./select";
+import type { ModelRegistryEntry } from "./models";
+
+export type FetchListArgs = {
+  select: SelectShape;
+  limit?: number;
+  offset?: number;
+  locale?: string;
+  where?: Record<string, unknown>;
+  status?: string;
+  statusIn?: string[];
+  statusNotIn?: string[];
+  [key: string]: unknown;
+};
+
+export type FetchOneArgs = {
+  select: SelectShape;
+  id?: string;
+  locale?: string;
+  status?: string;
+  statusIn?: string[];
+  statusNotIn?: string[];
+  where?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+const RESERVED_LIST_KEYS = new Set(["select", "signal", "operationName"]);
+const RESERVED_ONE_KEYS = new Set(["select", "signal", "operationName"]);
+
+function collectVariables(
+  args: Record<string, unknown>,
+  reserved: Set<string>,
+  model?: ModelRegistryEntry,
+): { variables: Record<string, unknown>; variableDefs: string[]; argList: string[] } {
+  const variables: Record<string, unknown> = {};
+  const variableDefs: string[] = [];
+  const argList: string[] = [];
+
+  for (const [key, value] of Object.entries(args)) {
+    if (reserved.has(key) || value === undefined) {
+      continue;
+    }
+    const varName = key;
+    variables[varName] = value;
+    variableDefs.push(`$${varName}: ${graphqlVariableType(key, model)}`);
+    argList.push(`${key}: $${varName}`);
+  }
+
+  return { variables, variableDefs, argList };
+}
+
+function graphqlVariableType(key: string, model?: ModelRegistryEntry): string {
+  if (key === "limit" || key === "offset") {
+    return "Int";
+  }
+  if (key === "id") {
+    return "ID";
+  }
+  if (key === "statusIn" || key === "statusNotIn") {
+    return "[EntryStatus!]";
+  }
+  if (key === "status") {
+    return "EntryStatus";
+  }
+  if (key === "where" && model?.whereInput) {
+    return model.whereInput;
+  }
+  return "String";
+}
+
+export function buildFetchListQuery(model: ModelRegistryEntry, args: FetchListArgs): {
+  query: string;
+  variables: Record<string, unknown>;
+  operationName: string;
+  resultKey: string;
+} {
+  const selection = buildSelectionSet(args.select);
+  if (!selection) {
+    throw new Error("select must include at least one field");
+  }
+
+  const field = model.isSingleton ? model.singular : model.plural;
+  const operationName = `Fetch${model.apiId}List`;
+  const { select: _select, ...rest } = args;
+  const { variables, variableDefs, argList } = collectVariables(rest, RESERVED_LIST_KEYS, model);
+  const fieldArgs = argList.length > 0 ? `(${argList.join(", ")})` : "";
+  const varDefs = variableDefs.length > 0 ? `(${variableDefs.join(", ")})` : "";
+
+  const query = `query ${operationName}${varDefs} {
+  ${field}${fieldArgs} {
+    ${selection}
+  }
+}`;
+
+  return { query, variables, operationName, resultKey: field };
+}
+
+export function buildFetchOneQuery(model: ModelRegistryEntry, args: FetchOneArgs): {
+  query: string;
+  variables: Record<string, unknown>;
+  operationName: string;
+  resultKey: string;
+} {
+  const selection = buildSelectionSet(args.select);
+  if (!selection) {
+    throw new Error("select must include at least one field");
+  }
+
+  const field = model.singular;
+  const operationName = `Fetch${model.apiId}One`;
+  const { select: _select, ...rest } = args;
+  const { variables, variableDefs, argList } = collectVariables(rest, RESERVED_ONE_KEYS, model);
+  const fieldArgs = argList.length > 0 ? `(${argList.join(", ")})` : "";
+  const varDefs = variableDefs.length > 0 ? `(${variableDefs.join(", ")})` : "";
+
+  const query = `query ${operationName}${varDefs} {
+  ${field}${fieldArgs} {
+    ${selection}
+  }
+}`;
+
+  return { query, variables, operationName, resultKey: field };
+}

package/clients/typescript/src/index.ts

@@ -0,0 +1,41 @@
+export {
+  ContismoClient,
+  type ContismoClientOptions,
+  type FetchOptions,
+  type FetchOneOptions,
+} from "./client";
+export { resolveContismoClientConfig } from "./load-client";
+export { findConfigFile, loadContismoConfig } from "./load-config";
+export { loadContismoModels } from "./load-models";
+export type { ModelRegistry, ModelRegistryEntry } from "./models";
+export type { SelectShape } from "./select";
+export type { FetchListArgs, FetchOneArgs } from "./fetch-query";
+export {
+  READ_ONLY_API_KEY_PREFIX,
+  READ_WRITE_API_KEY_PREFIX,
+  isReadOnlyApiKey,
+  isReadWriteApiKey,
+} from "./api-keys";
+export {
+  ContismoError,
+  ContismoGraphQLError,
+  ContismoHttpError,
+  ContismoErrorCodes,
+  isContismoError,
+} from "./errors";
+export {
+  INTROSPECTION_QUERY,
+  type IntrospectionQueryResult,
+  type IntrospectionSchema,
+  type IntrospectionType,
+  type IntrospectionField,
+  type IntrospectionTypeRef,
+} from "./introspection";
+export { writeIntrospectionResult } from "./write-introspection";
+export type {
+  ContismoClientConfig,
+  RequestOptions,
+  GraphQLResponse,
+  GraphQLResponseError,
+  GraphQLErrorExtensions,
+} from "./types";

package/clients/typescript/src/introspection.ts

@@ -0,0 +1,165 @@
+/**
+ * Standard GraphQL introspection query (compatible with GraphiQL and graphql-codegen).
+ * @see https://spec.graphql.org/draft/#sec-Introspection
+ */
+export const INTROSPECTION_QUERY = /* GraphQL */ `
+  query IntrospectionQuery {
+    __schema {
+      queryType {
+        name
+      }
+      mutationType {
+        name
+      }
+      subscriptionType {
+        name
+      }
+      types {
+        ...FullType
+      }
+      directives {
+        name
+        description
+        locations
+        args {
+          ...InputValue
+        }
+      }
+    }
+  }
+
+  fragment FullType on __Type {
+    kind
+    name
+    description
+    fields(includeDeprecated: true) {
+      name
+      description
+      args {
+        ...InputValue
+      }
+      type {
+        ...TypeRef
+      }
+      isDeprecated
+      deprecationReason
+    }
+    inputFields {
+      ...InputValue
+    }
+    interfaces {
+      ...TypeRef
+    }
+    enumValues(includeDeprecated: true) {
+      name
+      description
+      isDeprecated
+      deprecationReason
+    }
+    possibleTypes {
+      ...TypeRef
+    }
+  }
+
+  fragment InputValue on __InputValue {
+    name
+    description
+    type {
+      ...TypeRef
+    }
+    defaultValue
+  }
+
+  fragment TypeRef on __Type {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+        ofType {
+          kind
+          name
+          ofType {
+            kind
+            name
+            ofType {
+              kind
+              name
+              ofType {
+                kind
+                name
+                ofType {
+                  kind
+                  name
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+/** Subset of the introspection query result used by codegen tools. */
+export type IntrospectionQueryResult = {
+  __schema: IntrospectionSchema;
+};
+
+export type IntrospectionSchema = {
+  queryType: { name: string } | null;
+  mutationType: { name: string } | null;
+  subscriptionType: { name: string } | null;
+  types: readonly IntrospectionType[];
+  directives: readonly IntrospectionDirective[];
+};
+
+export type IntrospectionType = {
+  kind: string;
+  name: string | null;
+  description?: string | null;
+  fields?: readonly IntrospectionField[] | null;
+  inputFields?: readonly IntrospectionInputValue[] | null;
+  interfaces?: readonly IntrospectionTypeRef[] | null;
+  enumValues?: readonly IntrospectionEnumValue[] | null;
+  possibleTypes?: readonly IntrospectionTypeRef[] | null;
+};
+
+export type IntrospectionField = {
+  name: string;
+  description?: string | null;
+  args: readonly IntrospectionInputValue[];
+  type: IntrospectionTypeRef;
+  isDeprecated: boolean;
+  deprecationReason?: string | null;
+};
+
+export type IntrospectionInputValue = {
+  name: string;
+  description?: string | null;
+  type: IntrospectionTypeRef;
+  defaultValue?: string | null;
+};
+
+export type IntrospectionEnumValue = {
+  name: string;
+  description?: string | null;
+  isDeprecated: boolean;
+  deprecationReason?: string | null;
+};
+
+export type IntrospectionDirective = {
+  name: string;
+  description?: string | null;
+  locations: readonly string[];
+  args: readonly IntrospectionInputValue[];
+};
+
+export type IntrospectionTypeRef = {
+  kind: string;
+  name: string | null;
+  ofType?: IntrospectionTypeRef | null;
+};

package/clients/typescript/src/load-client.ts

@@ -0,0 +1,47 @@
+import { findConfigFile, loadContismoConfig } from "./load-config";
+import { loadContismoModels } from "./load-models";
+import type { ContismoClientConfig } from "./types";
+
+export type ContismoClientOptions = {
+  /** Working directory for config and generated file discovery. Default: `process.cwd()`. */
+  cwd?: string;
+  /** Path to `contismo.config.*` when it is not in the project root. */
+  config?: string;
+} & Partial<Omit<ContismoClientConfig, "models">>;
+
+function hasExplicitCredentials(
+  options: ContismoClientConfig | ContismoClientOptions,
+): options is ContismoClientConfig {
+  return typeof options.apiKey === "string" && options.apiKey.length > 0;
+}
+
+/**
+ * Resolve client settings from explicit credentials or `contismo.config.*` plus the generated model registry.
+ */
+export function resolveContismoClientConfig(
+  options: ContismoClientConfig | ContismoClientOptions = {},
+): ContismoClientConfig {
+  const cwd =
+    "cwd" in options && options.cwd !== undefined ? options.cwd : process.cwd();
+
+  if (hasExplicitCredentials(options)) {
+    if (options.models) {
+      return options;
+    }
+    if (findConfigFile(cwd)) {
+      const fileConfig = loadContismoConfig(cwd);
+      return { ...options, models: loadContismoModels(cwd, fileConfig.codegen) };
+    }
+    return options;
+  }
+
+  const { cwd: _cwd, config: configPath, ...overrides } = options as ContismoClientOptions;
+  const fileConfig = loadContismoConfig(cwd, configPath);
+  const models = loadContismoModels(cwd, fileConfig.codegen);
+
+  return {
+    ...fileConfig.client,
+    ...overrides,
+    models,
+  };
+}

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

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createJiti } from "jiti";
+import type { ContismoConfig } from "./config";
+
+const CONFIG_NAMES = [
+  "contismo.config.ts",
+  "contismo.config.mts",
+  "contismo.config.js",
+  "contismo.config.mjs",
+  "contismo.config.cjs",
+  "contismo.config.json",
+] as const;
+
+export function findConfigFile(cwd: string): string | null {
+  for (const name of CONFIG_NAMES) {
+    const path = resolve(cwd, name);
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+  return null;
+}
+
+export function loadContismoConfig(cwd: string, configPath?: string): ContismoConfig {
+  const resolved =
+    configPath !== undefined ? resolve(cwd, configPath) : findConfigFile(cwd);
+
+  if (!resolved || !existsSync(resolved)) {
+    throw new Error(
+      `No Contismo config found in ${cwd}. Create contismo.config.ts:\n\n` +
+        `  import { defineConfig } from "@contismo/sdk/config";\n\n` +
+        `  export default defineConfig({\n` +
+        `    client: { apiKey: "gql_…", endpoint: "https://graphql.contismo.com", project: "…", environment: "production" },\n` +
+        `  });\n`,
+    );
+  }
+
+  if (resolved.endsWith(".json")) {
+    const config = JSON.parse(readFileSync(resolved, "utf8")) as ContismoConfig;
+    assertConfig(config, resolved);
+    return config;
+  }
+
+  const jiti = createJiti(cwd, { interopDefault: true });
+  const loaded = jiti(resolved) as { default?: ContismoConfig } | ContismoConfig;
+  const config = (loaded as { default?: ContismoConfig }).default ?? (loaded as ContismoConfig);
+  assertConfig(config, resolved);
+  return config;
+}
+
+function assertConfig(config: unknown, path: string): asserts config is ContismoConfig {
+  if (!config || typeof config !== "object" || !("client" in config)) {
+    throw new Error(`Invalid config at ${path}: expected { client: { apiKey, endpoint, project, environment } }`);
+  }
+
+  const { client } = config as ContismoConfig;
+  const required = ["apiKey", "endpoint", "project", "environment"] as const;
+  for (const key of required) {
+    if (typeof client[key] !== "string" || client[key].length === 0) {
+      throw new Error(`Invalid config at ${path}: client.${key} is required`);
+    }
+  }
+}

package/clients/typescript/src/load-models.ts

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import { createJiti } from "jiti";
+import type { ContismoCodegenConfig } from "./config";
+import type { ModelRegistry } from "./models";
+import { resolveCodegenPaths } from "./resolve-codegen-paths";
+
+export function loadContismoModels(cwd: string, codegen?: ContismoCodegenConfig): ModelRegistry {
+  const { modelsPath } = resolveCodegenPaths(cwd, codegen);
+
+  if (!existsSync(modelsPath)) {
+    throw new Error(
+      `Model registry not found at ${modelsPath}. Run \`contismo generate\` first.`,
+    );
+  }
+
+  const jiti = createJiti(cwd, { interopDefault: true });
+  const loaded = jiti(modelsPath) as {
+    contismoModels?: ModelRegistry;
+    default?: ModelRegistry | { contismoModels?: ModelRegistry };
+  };
+
+  const raw =
+    loaded.contismoModels ??
+    (loaded.default && typeof loaded.default === "object" && "contismoModels" in loaded.default
+      ? (loaded.default as { contismoModels?: ModelRegistry }).contismoModels
+      : loaded.default);
+
+  if (!raw || typeof raw !== "object") {
+    throw new Error(
+      `Expected \`contismoModels\` export in ${modelsPath}. Run \`contismo generate\`.`,
+    );
+  }
+
+  return raw as ModelRegistry;
+}

package/clients/typescript/src/models.ts

@@ -0,0 +1,16 @@
+export type ModelRegistryEntry = {
+  /** Content model API ID (e.g. `Test`). */
+  apiId: string;
+  /** GraphQL query field for one entry (e.g. `test`). */
+  singular: string;
+  /** GraphQL query field for many entries (e.g. `tests`). Same as `singular` when singleton. */
+  plural: string;
+  /** GraphQL object type name (e.g. `Entry_Test`). */
+  graphqlType: string;
+  /** When true, only the singular field exists on Query. */
+  isSingleton?: boolean;
+  /** GraphQL input type for `where` on list queries (e.g. `Entry_Test_WhereInput`). */
+  whereInput?: string;
+};
+
+export type ModelRegistry = Record<string, ModelRegistryEntry>;

package/clients/typescript/src/request-payload.ts

@@ -0,0 +1,16 @@
+import type { GraphQLRequestPayload } from "./types";
+
+export function buildGraphQLPayload(
+  query: string,
+  variables?: Record<string, unknown>,
+  operationName?: string,
+): GraphQLRequestPayload {
+  const payload: GraphQLRequestPayload = { query };
+  if (variables !== undefined) {
+    payload.variables = variables;
+  }
+  if (operationName !== undefined) {
+    payload.operationName = operationName;
+  }
+  return payload;
+}

package/clients/typescript/src/resolve-codegen-paths.ts

@@ -0,0 +1,31 @@
+import { dirname, join, resolve } from "node:path";
+import type { ContismoCodegenConfig } from "./config";
+
+export type ResolvedCodegenPaths = {
+  schemaPath: string;
+  outputPath: string;
+  modelsPath: string;
+};
+
+export function resolveCodegenPaths(cwd: string, codegen?: ContismoCodegenConfig): ResolvedCodegenPaths {
+  const schemaPath =
+    codegen?.schema !== undefined
+      ? resolve(cwd, codegen.schema)
+      : join(resolve(cwd, codegen?.schemaDir ?? "contismo"), codegen?.schemaFile ?? "schema.json");
+
+  const outputDir = resolve(cwd, codegen?.outputDir ?? "src/generated");
+
+  const outputPath =
+    codegen?.output !== undefined
+      ? resolve(cwd, codegen.output)
+      : join(outputDir, codegen?.outputFile ?? "contismo.ts");
+
+  const modelsDir = codegen?.output !== undefined ? dirname(outputPath) : outputDir;
+
+  const modelsPath =
+    codegen?.models !== undefined
+      ? resolve(cwd, codegen.models)
+      : join(modelsDir, codegen?.modelsFile ?? "contismo-models.ts");
+
+  return { schemaPath, outputPath, modelsPath };
+}

package/clients/typescript/src/select.ts

@@ -0,0 +1,22 @@
+export type SelectShape = {
+  [field: string]: boolean | SelectShape;
+};
+
+export function buildSelectionSet(select: SelectShape): string {
+  const parts: string[] = [];
+
+  for (const [key, value] of Object.entries(select)) {
+    if (value === true) {
+      parts.push(key);
+      continue;
+    }
+    if (value && typeof value === "object") {
+      const nested = buildSelectionSet(value);
+      if (nested.length > 0) {
+        parts.push(`${key} { ${nested} }`);
+      }
+    }
+  }
+
+  return parts.join(" ");
+}

package/clients/typescript/src/types.ts

@@ -0,0 +1,55 @@
+import type { ModelRegistry } from "./models";
+
+export type ContismoClientConfig = {
+  /** GraphQL API key (`gql_…` or `gqlw_…`). */
+  apiKey: string;
+  /** Full GraphQL endpoint URL from Studio settings. */
+  endpoint: string;
+  /** Project ID from Studio (sent as `X-Project-Id`). */
+  project: string;
+  /** Environment apiId (sent as `X-Environment`). */
+  environment: string;
+  /**
+   * Model registry from generated `contismo-models.ts`.
+   * Loaded automatically when constructing from config; only pass manually for custom setups.
+   */
+  models?: ModelRegistry;
+  /** Custom fetch implementation (defaults to global `fetch`). */
+  fetch?: typeof fetch;
+  /** Additional headers merged after SDK defaults. */
+  headers?: Record<string, string>;
+  /** Optional `X-Request-Id` applied to every request when set. */
+  requestId?: string;
+};
+
+export type RequestOptions = {
+  signal?: AbortSignal;
+  operationName?: string;
+};
+
+export type GraphQLRequestPayload = {
+  query: string;
+  variables?: Record<string, unknown>;
+  operationName?: string;
+};
+
+export type GraphQLResponse<TData> = {
+  data?: TData;
+  errors?: GraphQLResponseError[];
+};
+
+export type GraphQLResponseError = {
+  message: string;
+  extensions?: GraphQLErrorExtensions;
+};
+
+export type GraphQLErrorExtensions = {
+  code?: string;
+  lockedByUserId?: string;
+  lockedByName?: string | null;
+  limitType?: string;
+  currentUsage?: number;
+  limit?: number;
+  retryAfterSeconds?: number;
+  [key: string]: unknown;
+};

package/clients/typescript/src/write-introspection.ts

@@ -0,0 +1,13 @@
+import { writeFile } from "node:fs/promises";
+import type { IntrospectionQueryResult } from "./introspection";
+
+/**
+ * Writes an introspection result to disk (for offline graphql-codegen runs).
+ */
+export async function writeIntrospectionResult(
+  result: IntrospectionQueryResult,
+  filePath: string,
+): Promise<void> {
+  const payload = { data: result };
+  await writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}

package/clients/typescript/tests/api-keys.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { isReadOnlyApiKey, isReadWriteApiKey } from "../src/api-keys";
+
+describe("api key helpers", () => {
+  it("identifies read-only keys", () => {
+    expect(isReadOnlyApiKey("gql_abc")).toBe(true);
+    expect(isReadWriteApiKey("gql_abc")).toBe(false);
+  });
+
+  it("identifies read-write keys", () => {
+    expect(isReadWriteApiKey("gqlw_abc")).toBe(true);
+    expect(isReadOnlyApiKey("gqlw_abc")).toBe(false);
+  });
+});