@supacloud/compiler 0.39.0 → 0.40.1

package/dist/graphql-client.d.ts

@@ -1,2 +1,2 @@
 /** Appended to the generated SDK; browser consumers need only the platform fetch API. */
-export declare const GRAPHQL_CLIENT_SOURCE = "\nexport interface GraphqlClientOptions {\n  /** Project base URL, not the management API URL. HTTPS is required outside loopback. */\n  url: string;\n  /** Public project key only. Never put a service-role or management key in a browser. */\n  publishableKey?: string;\n  /** Resolved on every request so session refresh and logout are observed. */\n  getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;\n  fetch?: (url: string, init: RequestInit) => Promise<Response>;\n}\n\nexport interface GraphqlRequestOptions {\n  signal?: AbortSignal;\n}\n\nexport class GraphqlRequestError extends Error {\n  constructor(\n    public readonly code: \"http\" | \"graphql\" | \"invalid-response\",\n    message: string,\n    public readonly status?: number,\n    public readonly errors?: readonly unknown[],\n  ) {\n    super(message);\n    this.name = \"GraphqlRequestError\";\n  }\n}\n\nexport function createGraphqlClient(options: GraphqlClientOptions) {\n  const endpoint = new URL(options.url);\n  const loopback = [\"localhost\", \"127.0.0.1\", \"[::1]\"].includes(endpoint.hostname);\n  if (endpoint.protocol !== \"https:\" && !(endpoint.protocol === \"http:\" && loopback)) {\n    throw new Error(\"GraphQL requires HTTPS outside loopback development.\");\n  }\n  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {\n    throw new Error(\"GraphQL project URLs must not contain credentials, query parameters or fragments.\");\n  }\n  endpoint.pathname = endpoint.pathname.replace(/\\/$/, \"\") + \"/graphql/v1\";\n  const fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);\n  return getSdk<GraphqlRequestOptions>(async (\n    query: string,\n    variables?: unknown,\n    request?: GraphqlRequestOptions,\n  ): Promise<unknown> => {\n    const headers = new Headers({ \"Content-Type\": \"application/json\", Accept: \"application/json\" });\n    if (options.publishableKey) headers.set(\"apikey\", options.publishableKey);\n    const token = await options.getAccessToken?.();\n    if (token) headers.set(\"Authorization\", \"Bearer \" + token);\n    const response = await fetcher(endpoint.toString(), {\n      method: \"POST\",\n      headers,\n      body: JSON.stringify({ query, variables }),\n      ...(request?.signal ? { signal: request.signal } : {}),\n      redirect: \"error\",\n    });\n    if (!response.ok) {\n      throw new GraphqlRequestError(\"http\", \"GraphQL HTTP request failed (\" + response.status + \").\", response.status);\n    }\n    let envelope: unknown;\n    try {\n      envelope = await response.json();\n    } catch {\n      throw new GraphqlRequestError(\"invalid-response\", \"GraphQL returned invalid JSON.\", response.status);\n    }\n    if (!envelope || typeof envelope !== \"object\" || Array.isArray(envelope)) {\n      throw new GraphqlRequestError(\"invalid-response\", \"GraphQL returned an invalid envelope.\", response.status);\n    }\n    if (\"errors\" in envelope) {\n      if (!Array.isArray(envelope.errors)) {\n        throw new GraphqlRequestError(\"invalid-response\", \"GraphQL returned invalid errors.\", response.status);\n      }\n      if (envelope.errors.length > 0) {\n        throw new GraphqlRequestError(\"graphql\", \"GraphQL query failed.\", response.status, envelope.errors);\n      }\n    }\n    if (!(\"data\" in envelope) || !envelope.data || typeof envelope.data !== \"object\" || Array.isArray(envelope.data)) {\n      throw new GraphqlRequestError(\"invalid-response\", \"GraphQL returned no result object.\", response.status);\n    }\n    // The operation-specific parser in getSdk validates selected field values.\n    return envelope.data;\n  });\n}\n";
+export declare const GRAPHQL_CLIENT_SOURCE = "\nexport interface GraphqlClientOptions {\n  /** Project base URL, not the management API URL. HTTPS is required outside loopback. */\n  url: string;\n  /** Public project key only. Never put a service-role or management key in a browser. */\n  publishableKey?: string;\n  /** Resolved on every request so session refresh and logout are observed. */\n  getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;\n  /** Include the persisted-operation SHA while retaining the full query for pg_graphql compatibility. */\n  persistedOperations?: boolean;\n  fetch?: (url: string, init: RequestInit) => Promise<Response>;\n}\n\nexport interface GraphqlRequestOptions {\n  signal?: AbortSignal;\n}\n\nexport interface GraphqlOperationMetadata {\n  name: string;\n  sha256: string;\n}\n\nexport class GraphqlRequestError extends Error {\n  constructor(\n    public readonly code: \"http\" | \"graphql\" | \"invalid-response\",\n    message: string,\n    public readonly status?: number,\n    public readonly errors?: readonly unknown[],\n  ) {\n    super(message);\n    this.name = \"GraphqlRequestError\";\n  }\n}\n\nexport function createGraphqlClient(options: GraphqlClientOptions) {\n  const endpoint = new URL(options.url);\n  const loopback = [\"localhost\", \"127.0.0.1\", \"[::1]\"].includes(endpoint.hostname);\n  if (endpoint.protocol !== \"https:\" && !(endpoint.protocol === \"http:\" && loopback)) {\n    throw new Error(\"GraphQL requires HTTPS outside loopback development.\");\n  }\n  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {\n    throw new Error(\"GraphQL project URLs must not contain credentials, query parameters or fragments.\");\n  }\n  endpoint.pathname = endpoint.pathname.replace(/\\/$/, \"\") + \"/graphql/v1\";\n  const fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);\n  return getSdk<GraphqlRequestOptions>(async (\n    query: string,\n    variables?: unknown,\n    request?: GraphqlRequestOptions,\n    operation?: GraphqlOperationMetadata,\n  ): Promise<unknown> => {\n    const headers = new Headers({ \"Content-Type\": \"application/json\", Accept: \"application/json\" });\n    if (options.publishableKey) headers.set(\"apikey\", options.publishableKey);\n    const token = await options.getAccessToken?.();\n    if (token) headers.set(\"Authorization\", \"Bearer \" + token);\n    const response = await fetcher(endpoint.toString(), {\n      method: \"POST\",\n      headers,\n      body: JSON.stringify({\n        query,\n        variables,\n        ...(operation?.name ? { operationName: operation.name } : {}),\n        ...(options.persistedOperations === false || !operation?.sha256 ? {} : {\n          extensions: {\n            persistedQuery: { version: 1, sha256Hash: operation.sha256 },\n          },\n        }),\n      }),\n      ...(request?.signal ? { signal: request.signal } : {}),\n      redirect: \"error\",\n    });\n    if (!response.ok) {\n      throw new GraphqlRequestError(\"http\", \"GraphQL HTTP request failed (\" + response.status + \").\", response.status);\n    }\n    let envelope: unknown;\n    try {\n      envelope = await response.json();\n    } catch {\n      throw new GraphqlRequestError(\"invalid-response\", \"GraphQL returned invalid JSON.\", response.status);\n    }\n    if (!envelope || typeof envelope !== \"object\" || Array.isArray(envelope)) {\n      throw new GraphqlRequestError(\"invalid-response\", \"GraphQL returned an invalid envelope.\", response.status);\n    }\n    if (\"errors\" in envelope) {\n      if (!Array.isArray(envelope.errors)) {\n        throw new GraphqlRequestError(\"invalid-response\", \"GraphQL returned invalid errors.\", response.status);\n      }\n      if (envelope.errors.length > 0) {\n        throw new GraphqlRequestError(\"graphql\", \"GraphQL query failed.\", response.status, envelope.errors);\n      }\n    }\n    if (!(\"data\" in envelope) || !envelope.data || typeof envelope.data !== \"object\" || Array.isArray(envelope.data)) {\n      throw new GraphqlRequestError(\"invalid-response\", \"GraphQL returned no result object.\", response.status);\n    }\n    // The operation-specific parser in getSdk validates selected field values.\n    return envelope.data;\n  });\n}\n";

package/dist/graphql-governance.d.ts

@@ -0,0 +1,92 @@
+import { type GraphQLSchema } from "graphql";
+export type GraphqlSeverity = "error" | "warn";
+export interface GraphqlGovernanceDiagnostic {
+    severity: GraphqlSeverity;
+    code: string;
+    message: string;
+    file?: string;
+    line?: number;
+    operation?: string;
+}
+export interface GraphqlGovernancePolicy {
+    /** Exact operation names or simple '*' suffix patterns. */
+    operations?: string[];
+    maxDepth?: number;
+    maxFields?: number;
+    maxComplexity?: number;
+    maxPageSize?: number;
+}
+export interface GraphqlOperationReport {
+    name: string;
+    operation: "query" | "mutation" | "subscription";
+    depth: number;
+    fields: number;
+    complexity: number;
+    pageSizes: number[];
+    allowed: boolean;
+}
+export interface GraphqlFeatureMatrix {
+    pgGraphql: "schema-snapshot";
+    query: boolean;
+    mutation: boolean;
+    subscription: boolean;
+    relayConnections: boolean;
+    filtering: boolean;
+    ordering: boolean;
+    aggregation: boolean;
+    byPk: boolean;
+    functions: boolean;
+}
+export interface GraphqlCompatibilityReport {
+    ok: boolean;
+    schema: {
+        path: string;
+        schemaHash: string;
+        schemaNormalizedHash: string;
+    };
+    features: GraphqlFeatureMatrix;
+    operations: GraphqlOperationReport[];
+    diagnostics: GraphqlGovernanceDiagnostic[];
+}
+export interface GraphqlSchemaChange {
+    severity: "breaking" | "non-breaking";
+    code: string;
+    message: string;
+    path: string;
+}
+export interface GraphqlSchemaDiff {
+    ok: boolean;
+    breaking: GraphqlSchemaChange[];
+    nonBreaking: GraphqlSchemaChange[];
+}
+export interface GraphqlRoleSnapshot {
+    role: string;
+    schema: string;
+    schemaHash: string;
+    schemaNormalizedHash: string;
+}
+export interface GraphqlRoleSnapshotReport {
+    ok: boolean;
+    roles: GraphqlRoleSnapshot[];
+    diagnostics: GraphqlGovernanceDiagnostic[];
+}
+export declare function schemaFromSource(source: string, path?: string): GraphQLSchema;
+export declare function readGraphqlSchema(path: string): Promise<{
+    path: string;
+    source: string;
+    schema: GraphQLSchema;
+    schemaHash: string;
+    schemaNormalizedHash: string;
+}>;
+export declare function graphqlFeatureMatrix(schema: GraphQLSchema): GraphqlFeatureMatrix;
+export declare function checkGraphqlCompatibility(schema: GraphQLSchema, documents: readonly {
+    source: string;
+    path?: string;
+}[], policy?: GraphqlGovernancePolicy): Omit<GraphqlCompatibilityReport, "schema">;
+export declare function diffGraphqlSchemas(previous: GraphQLSchema, current: GraphQLSchema): GraphqlSchemaDiff;
+export declare function createRoleSnapshotReport(roles: readonly {
+    role: string;
+    path: string;
+    source: string;
+}[]): GraphqlRoleSnapshotReport;
+export declare function introspectionQuery(): string;

package/dist/graphql-runtime.d.ts

@@ -2,4 +2,5 @@
  * Project the standard Codegen result types, rather than independently interpreting
  * selections, fragments and conditional fields. Unsupported wire types fail closed.
  */
-export declare function renderGraphqlValidators(source: string, operationNames: readonly string[]): string;
+export type GraphqlOperationKind = "query" | "mutation";
+export declare function renderGraphqlValidators(source: string, operationNames: readonly string[], operationKinds?: ReadonlyMap<string, GraphqlOperationKind>): string;

package/dist/index.d.ts

@@ -56,4 +56,6 @@ export type { ApplicationGraph, AspectRefNode, CachedModuleEntry, CheckProjectRe
 export { inspectRouteContracts, validateRouteContracts } from "./route-contracts";
 export { pullGraphqlSchema } from "./graphql-schema";
 export type { PullGraphqlSchemaOptions } from "./graphql-schema";
+export { checkGraphqlCompatibility, createRoleSnapshotReport, diffGraphqlSchemas, graphqlFeatureMatrix, introspectionQuery, readGraphqlSchema, schemaFromSource, } from "./graphql-governance";
+export type { GraphqlCompatibilityReport, GraphqlFeatureMatrix, GraphqlGovernanceDiagnostic, GraphqlGovernancePolicy, GraphqlOperationReport, GraphqlRoleSnapshot, GraphqlRoleSnapshotReport, GraphqlSchemaChange, GraphqlSchemaDiff, } from "./graphql-governance";
 export { generateDatabaseContracts, parseDatabaseContractsOptions, runDatabaseContractsFile, type DatabaseContractsOptions } from "./database-contracts";