@groundcover/api-client 0.1.0

package/dist/_generated/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

package/dist/client.d.ts

@@ -0,0 +1,52 @@
+export interface GroundcoverConfig {
+    /**
+     * The API Key for the groundcover backend.
+     * If not provided, it will fallback to the GC_API_KEY environment variable.
+     */
+    apiKey?: string;
+    /**
+     * The Backend ID (tenant ID) for your environment.
+     * If not provided, it will fallback to the GC_BACKEND_ID environment variable.
+     */
+    backendId?: string;
+    /**
+     * The Base URL of the groundcover API.
+     * Defaults to 'https://api.groundcover.com' or the GC_BASE_URL environment variable.
+     */
+    baseUrl?: string;
+    /**
+     * Maximum number of automatic retries on failure (default: 3).
+     */
+    maxRetries?: number;
+    /**
+     * Request timeout in milliseconds (default: 30000).
+     */
+    timeout?: number;
+    /**
+     * If true, allows creating the client without an API Key or Backend ID.
+     * Useful for hitting public endpoints or if auth is handled externally.
+     */
+    allowUnauthenticated?: boolean;
+    /**
+     * Custom fetch implementation to use instead of the global fetch.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Minimum wait time between retries in milliseconds (default: 1000).
+     */
+    minRetryWait?: number;
+    /**
+     * Maximum wait time between retries in milliseconds (default: 30000).
+     */
+    maxRetryWait?: number;
+    /**
+     * Array of HTTP status codes that trigger a retry (default: [429, 503]).
+     */
+    retryStatuses?: number[];
+    /**
+     * Default traceparent header to include in all requests.
+     * Can also be set via the GC_TRACEPARENT environment variable.
+     */
+    traceparent?: string;
+}
+export declare function initClient(config?: GroundcoverConfig): import("./_generated/client/types.gen.js").Client;

package/dist/client.js

@@ -0,0 +1,189 @@
+import pRetry, { AbortError } from 'p-retry';
+import { createClient } from './_generated/client/index.js';
+class RetryableResponseError extends Error {
+    response;
+    constructor(response) {
+        super(`Retryable status code: ${response.status}`);
+        this.response = response;
+        this.name = 'RetryableResponseError';
+    }
+}
+// HTTP methods that are safe to replay after the server has already responded
+// with a retryable status.
+const IDEMPOTENT_METHODS = ['GET', 'HEAD', 'OPTIONS', 'TRACE'];
+function isIdempotentMethod(method) {
+    return IDEMPOTENT_METHODS.includes(method.toUpperCase());
+}
+/**
+ * Initializes and returns a new groundcover SDK client.
+ * Must be called before using any API services.
+ *
+ * @param config - Optional configuration object.
+ */
+function normalizeBaseUrl(baseUrl) {
+    if (!baseUrl)
+        return '';
+    if (baseUrl.startsWith('//'))
+        return `https:${baseUrl}`;
+    if (baseUrl.startsWith('/') && !baseUrl.startsWith('//'))
+        return `https://${baseUrl.replace(/^\/+/, '')}`;
+    if (!baseUrl.includes('://'))
+        return `https://${baseUrl}`;
+    return baseUrl;
+}
+function getEnvVar(key) {
+    if (typeof process !== 'undefined' && process.env) {
+        return process.env[key];
+    }
+    // Safely check for Deno global without requiring Deno types in the TS config
+    // biome-ignore lint/suspicious/noExplicitAny: Safely checking for Deno global
+    const globalDeno = globalThis.Deno;
+    if (globalDeno?.env) {
+        return globalDeno.env.get(key);
+    }
+    return undefined;
+}
+/**
+ * Polyfill for AbortSignal.any() to support Node 18 environments.
+ */
+function combineSignals(signal1, signal2) {
+    if (!signal1)
+        return signal2;
+    if (!signal2)
+        return signal1;
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any([signal1, signal2]);
+    }
+    const controller = new AbortController();
+    const onAbort = () => {
+        controller.abort(signal1.aborted ? signal1.reason : signal2.reason);
+        signal1.removeEventListener('abort', onAbort);
+        signal2.removeEventListener('abort', onAbort);
+    };
+    if (signal1.aborted || signal2.aborted) {
+        onAbort();
+    }
+    else {
+        signal1.addEventListener('abort', onAbort);
+        signal2.addEventListener('abort', onAbort);
+    }
+    return controller.signal;
+}
+export function initClient(config) {
+    const apiKey = config?.apiKey || getEnvVar('GC_API_KEY');
+    const backendId = config?.backendId || getEnvVar('GC_BACKEND_ID');
+    const rawBaseUrl = config?.baseUrl || getEnvVar('GC_BASE_URL') || 'https://api.groundcover.com';
+    const baseUrl = normalizeBaseUrl(rawBaseUrl);
+    const maxRetries = config?.maxRetries ?? 3;
+    const traceparent = config?.traceparent || getEnvVar('GC_TRACEPARENT');
+    const timeout = config?.timeout ?? 30000;
+    const activeFetch = config?.fetch ?? globalThis.fetch;
+    const retryStatuses = config?.retryStatuses && config.retryStatuses.length > 0 ? config.retryStatuses : [429, 503];
+    const allowUnauthenticated = config?.allowUnauthenticated ?? false;
+    if (!allowUnauthenticated && !apiKey) {
+        throw new Error('groundcover API key is required. Pass it via config or set GC_API_KEY environment variable.');
+    }
+    if (!allowUnauthenticated && !backendId) {
+        throw new Error('groundcover Backend ID is required. Pass it via config or set GC_BACKEND_ID environment variable.');
+    }
+    const headers = {
+        'User-Agent': 'groundcover-ts-sdk',
+    };
+    if (apiKey)
+        headers.Authorization = `Bearer ${apiKey}`;
+    if (backendId)
+        headers['X-Backend-Id'] = backendId;
+    if (traceparent) {
+        headers.traceparent = traceparent;
+    }
+    const client = createClient({
+        baseUrl,
+        headers,
+        // Override fetch to add retries and content-type fixes
+        fetch: async (input, init) => {
+            // Create the base Request once. If input is already a Request, we clone it
+            // so we don't consume the caller's instance. If it's a URL/string, we construct it.
+            const baseReq = input instanceof Request ? input.clone() : new Request(input, init);
+            const runFetch = async () => {
+                // Clone for each attempt so the body isn't consumed
+                const req = baseReq.clone();
+                let res;
+                try {
+                    const controller = new AbortController();
+                    const timeoutId = setTimeout(() => controller.abort(new Error('Timeout')), timeout);
+                    const signal = combineSignals(req.signal, controller.signal);
+                    try {
+                        res = await activeFetch(req, { signal });
+                    }
+                    finally {
+                        clearTimeout(timeoutId);
+                    }
+                }
+                catch (err) {
+                    // Only retry transport errors for idempotent methods (matches Go/Python SDKs).
+                    if (isIdempotentMethod(req.method)) {
+                        throw err; // Allow p-retry to handle it
+                    }
+                    throw new AbortError(err);
+                }
+                // Fix response content-type for monitor YAML GETs
+                if (req.method === 'GET' && res.status === 200) {
+                    const url = new URL(req.url);
+                    const path = url.pathname.replace(/\/$/, '');
+                    const parts = path.split('/');
+                    // /api/monitors/{id}
+                    if (parts.length >= 4 && parts[parts.length - 2] === 'monitors') {
+                        const segment = parts[parts.length - 1];
+                        if (!['silences', 'list', 'recurring-silences'].includes(segment)) {
+                            const contentType = res.headers.get('content-type') || '';
+                            if (!contentType.startsWith('application/x-yaml')) {
+                                // To mutate headers we need to reconstruct the response
+                                const newHeaders = new Headers(res.headers);
+                                newHeaders.set('content-type', 'application/x-yaml');
+                                return new Response(res.body, {
+                                    status: res.status,
+                                    statusText: res.statusText,
+                                    headers: newHeaders,
+                                });
+                            }
+                        }
+                    }
+                }
+                // Trigger retry on certain status codes
+                if (retryStatuses.includes(res.status)) {
+                    // Do not retry non-idempotent requests
+                    if (!isIdempotentMethod(req.method)) {
+                        return res;
+                    }
+                    throw new RetryableResponseError(res);
+                }
+                // Also don't retry on other status codes
+                return res;
+            };
+            try {
+                return await pRetry(runFetch, {
+                    retries: maxRetries,
+                    minTimeout: config?.minRetryWait ?? 1000,
+                    maxTimeout: config?.maxRetryWait ?? 30000,
+                    factor: 2,
+                    randomize: true,
+                });
+            }
+            catch (err) {
+                if (err instanceof RetryableResponseError) {
+                    return err.response; // return the final response after exhaustion
+                }
+                throw err;
+            }
+        },
+    });
+    // Interceptor to clean up Content-Type and add retries (matching Go/Python SDKs)
+    client.interceptors.request.use((req, options) => {
+        // For GET/DELETE/HEAD requests, avoid sending a Content-Type.
+        if (['GET', 'DELETE', 'HEAD'].includes(req.method.toUpperCase())) {
+            req.headers.delete('Content-Type');
+        }
+        return req;
+    });
+    return client;
+}

package/dist/helpers.d.ts

@@ -0,0 +1,15 @@
+import type { Options } from './_generated/client/types.gen.js';
+import type { GetMonitorData } from './_generated/index.js';
+export type ParsedMonitorResponse = {
+    data: Record<string, unknown>;
+    error: null;
+    response: Response;
+} | {
+    data: undefined;
+    error: unknown;
+    response: Response;
+};
+/**
+ * Convenience method to get a monitor and parse its YAML response into an object.
+ */
+export declare function getMonitorParsed(options: Options<GetMonitorData>): Promise<ParsedMonitorResponse>;

package/dist/helpers.js

@@ -0,0 +1,24 @@
+import * as yaml from 'js-yaml';
+import { getMonitor } from './_generated/index.js';
+/**
+ * Convenience method to get a monitor and parse its YAML response into an object.
+ */
+export async function getMonitorParsed(options) {
+    const result = (await getMonitor({
+        ...options,
+        parseAs: 'text',
+    }));
+    if (result.error || !result.data) {
+        return { data: undefined, error: result.error, response: result.response };
+    }
+    try {
+        return {
+            data: yaml.load(result.data),
+            error: null,
+            response: result.response,
+        };
+    }
+    catch (e) {
+        return { data: undefined, error: e, response: result.response };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './client.js';
+export * from './helpers.js';
+export * from './_generated/index.js';
+export * from './types/conditions.js';
+export * from './types/matchers.js';
+export * from './utils/ConditionSet.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './client.js';
+export * from './helpers.js';
+export * from './_generated/index.js';
+export * from './types/conditions.js';
+export * from './types/matchers.js';
+export * from './utils/ConditionSet.js';

package/dist/types/conditions.d.ts

@@ -0,0 +1,25 @@
+/** Condition constants for the groundcover SDK. */
+export declare const CONDITION_ORIGIN_ROOT = "root";
+export declare const CONDITION_KEY_NAMESPACE = "namespace";
+export declare const CONDITION_KEY_WORKLOAD = "workload";
+export declare const CONDITION_KEY_POD_NAME = "podName";
+export declare const CONDITION_KEY_REASON = "reason";
+export declare const CONDITION_KEY_TYPE = "type";
+export declare const CONDITION_KEY_ENV = "env";
+export declare const CONDITION_KEY_INSTANCE = "instance";
+export declare const CONDITION_VALUE_OOM_KILLED = "OOMKilled";
+export declare const CONDITION_VALUE_TYPE_CONTAINER_CRASH = "container_crash";
+export declare const OPERATOR_EQUAL = "eq";
+export declare const OPERATOR_NOT_EQUAL = "ne";
+export declare const OPERATOR_CONTAINS = "contains";
+export declare const OPERATOR_NOT_CONTAINS = "notcontains";
+export declare const OPERATOR_CONTAINS_IGNORE_CASE = "icontains";
+export declare const OPERATOR_NOT_CONTAINS_IGNORE_CASE = "inotcontains";
+export declare const OPERATOR_STARTS_WITH = "startswith";
+export declare const OPERATOR_STARTS_WITH_IGNORE_CASE = "istartswith";
+export declare const CONDITION_TYPE_STRING = "string";
+export declare const CONDITION_TYPE_INT64 = "int64";
+export declare const CONDITION_TYPE_FLOAT64 = "float64";
+export declare const CONDITION_TYPE_BOOL = "bool";
+export declare const CONDITION_TYPE_DATETIME = "datetime";
+export declare const CONDITION_TYPE_STRING_ARRAY = "string_array";

package/dist/types/conditions.js

@@ -0,0 +1,30 @@
+/** Condition constants for the groundcover SDK. */
+// Condition fields
+export const CONDITION_ORIGIN_ROOT = 'root';
+// Condition keys
+export const CONDITION_KEY_NAMESPACE = 'namespace';
+export const CONDITION_KEY_WORKLOAD = 'workload';
+export const CONDITION_KEY_POD_NAME = 'podName';
+export const CONDITION_KEY_REASON = 'reason';
+export const CONDITION_KEY_TYPE = 'type';
+export const CONDITION_KEY_ENV = 'env';
+export const CONDITION_KEY_INSTANCE = 'instance';
+// Condition values
+export const CONDITION_VALUE_OOM_KILLED = 'OOMKilled';
+export const CONDITION_VALUE_TYPE_CONTAINER_CRASH = 'container_crash';
+// Filter operators
+export const OPERATOR_EQUAL = 'eq';
+export const OPERATOR_NOT_EQUAL = 'ne';
+export const OPERATOR_CONTAINS = 'contains';
+export const OPERATOR_NOT_CONTAINS = 'notcontains';
+export const OPERATOR_CONTAINS_IGNORE_CASE = 'icontains';
+export const OPERATOR_NOT_CONTAINS_IGNORE_CASE = 'inotcontains';
+export const OPERATOR_STARTS_WITH = 'startswith';
+export const OPERATOR_STARTS_WITH_IGNORE_CASE = 'istartswith';
+// Condition types
+export const CONDITION_TYPE_STRING = 'string';
+export const CONDITION_TYPE_INT64 = 'int64';
+export const CONDITION_TYPE_FLOAT64 = 'float64';
+export const CONDITION_TYPE_BOOL = 'bool';
+export const CONDITION_TYPE_DATETIME = 'datetime';
+export const CONDITION_TYPE_STRING_ARRAY = 'string_array';

package/dist/types/matchers.d.ts

@@ -0,0 +1,7 @@
+/** Match type enum for the groundcover SDK. */
+export declare enum FilterMatchType {
+    EQUAL = "=",
+    NOT_EQUAL = "!=",
+    REGEX = "=~",
+    NOT_REGEX = "!~"
+}

package/dist/types/matchers.js

@@ -0,0 +1,8 @@
+/** Match type enum for the groundcover SDK. */
+export var FilterMatchType;
+(function (FilterMatchType) {
+    FilterMatchType["EQUAL"] = "=";
+    FilterMatchType["NOT_EQUAL"] = "!=";
+    FilterMatchType["REGEX"] = "=~";
+    FilterMatchType["NOT_REGEX"] = "!~";
+})(FilterMatchType || (FilterMatchType = {}));

package/dist/utils/ConditionSet.d.ts

@@ -0,0 +1,47 @@
+import type { Condition } from '../_generated/index.js';
+/**
+ * Fluent builder for constructing a list of conditions.
+ *
+ * Uses default values for origin, type, and operator which can be overridden.
+ *
+ * Example:
+ * ```typescript
+ * import { ConditionSet } from '@groundcover/api-client';
+ *
+ * const conditions = new ConditionSet()
+ *   .add("namespace", "production")
+ *   .add("reason", "OOMKilled")
+ *   .addOomEventConditions()
+ *   .build();
+ * ```
+ */
+export declare class ConditionSet {
+    private conditions;
+    private defaultOrigin;
+    private defaultCondType;
+    private defaultOperator;
+    constructor(defaultOrigin?: string, defaultCondType?: string, defaultOperator?: string);
+    /**
+     * Add a condition, inferring the type from the JavaScript value type.
+     *
+     * Supports: string, string[], number (int/float inferred heuristically), boolean, Date.
+     */
+    add(key: string, value: unknown): ConditionSet;
+    /** Add a condition with explicit origin, type, operator, and value. */
+    addFull(key: string, origin: string, condType: string, value: string, operator: string): ConditionSet;
+    /** Add a pre-constructed condition object directly. */
+    addRaw(condition: Condition): ConditionSet;
+    /**
+     * Add predefined conditions to identify OOM events.
+     * Adds reason=OOMKilled and type=container_crash.
+     */
+    addOomEventConditions(): ConditionSet;
+    /** Return the final list of condition objects. */
+    build(): Condition[];
+    private addInternal;
+    /**
+     * Infer condition type and string value from a JavaScript value.
+     * Returns [valueStr, condType].
+     */
+    private inferType;
+}

package/dist/utils/ConditionSet.js

@@ -0,0 +1,95 @@
+import { CONDITION_KEY_REASON, CONDITION_KEY_TYPE, CONDITION_ORIGIN_ROOT, CONDITION_TYPE_BOOL, CONDITION_TYPE_DATETIME, CONDITION_TYPE_FLOAT64, CONDITION_TYPE_INT64, CONDITION_TYPE_STRING, CONDITION_TYPE_STRING_ARRAY, CONDITION_VALUE_OOM_KILLED, CONDITION_VALUE_TYPE_CONTAINER_CRASH, OPERATOR_EQUAL, } from '../types/conditions.js';
+/**
+ * Fluent builder for constructing a list of conditions.
+ *
+ * Uses default values for origin, type, and operator which can be overridden.
+ *
+ * Example:
+ * ```typescript
+ * import { ConditionSet } from '@groundcover/api-client';
+ *
+ * const conditions = new ConditionSet()
+ *   .add("namespace", "production")
+ *   .add("reason", "OOMKilled")
+ *   .addOomEventConditions()
+ *   .build();
+ * ```
+ */
+export class ConditionSet {
+    conditions = [];
+    defaultOrigin;
+    defaultCondType;
+    defaultOperator;
+    constructor(defaultOrigin = CONDITION_ORIGIN_ROOT, defaultCondType = CONDITION_TYPE_STRING, defaultOperator = OPERATOR_EQUAL) {
+        this.defaultOrigin = defaultOrigin;
+        this.defaultCondType = defaultCondType;
+        this.defaultOperator = defaultOperator;
+    }
+    /**
+     * Add a condition, inferring the type from the JavaScript value type.
+     *
+     * Supports: string, string[], number (int/float inferred heuristically), boolean, Date.
+     */
+    add(key, value) {
+        const [valueStr, condType] = this.inferType(value);
+        return this.addInternal(key, this.defaultOrigin, condType, valueStr, this.defaultOperator);
+    }
+    /** Add a condition with explicit origin, type, operator, and value. */
+    addFull(key, origin, condType, value, operator) {
+        return this.addInternal(key, origin, condType, value, operator);
+    }
+    /** Add a pre-constructed condition object directly. */
+    addRaw(condition) {
+        this.conditions.push(condition);
+        return this;
+    }
+    /**
+     * Add predefined conditions to identify OOM events.
+     * Adds reason=OOMKilled and type=container_crash.
+     */
+    addOomEventConditions() {
+        this.add(CONDITION_KEY_REASON, CONDITION_VALUE_OOM_KILLED);
+        this.add(CONDITION_KEY_TYPE, CONDITION_VALUE_TYPE_CONTAINER_CRASH);
+        return this;
+    }
+    /** Return the final list of condition objects. */
+    build() {
+        return [...this.conditions];
+    }
+    addInternal(key, origin, condType, value, operator) {
+        const condition = {
+            key,
+            origin,
+            type: condType,
+            filters: [{ op: operator, value }],
+        };
+        this.conditions.push(condition);
+        return this;
+    }
+    /**
+     * Infer condition type and string value from a JavaScript value.
+     * Returns [valueStr, condType].
+     */
+    inferType(value) {
+        if (typeof value === 'string') {
+            return [value, CONDITION_TYPE_STRING];
+        }
+        if (typeof value === 'boolean') {
+            return [String(value).toLowerCase(), CONDITION_TYPE_BOOL];
+        }
+        if (typeof value === 'number') {
+            if (Number.isInteger(value)) {
+                return [String(value), CONDITION_TYPE_INT64];
+            }
+            return [String(value), CONDITION_TYPE_FLOAT64];
+        }
+        if (value instanceof Date) {
+            return [value.toISOString(), CONDITION_TYPE_DATETIME];
+        }
+        if (Array.isArray(value)) {
+            return [JSON.stringify(value), CONDITION_TYPE_STRING_ARRAY];
+        }
+        // Fallback
+        return [String(value), this.defaultCondType];
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@groundcover/api-client",
+  "version": "0.1.0",
+  "description": "groundcover TypeScript API Client",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "devDependencies": {
+    "@biomejs/biome": "^1.8.0",
+    "@hey-api/openapi-ts": "0.99.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "typescript": "^6.0.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0",
+    "deno": ">=1.37.0"
+  },
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "js-yaml": "^5.2.1",
+    "p-retry": "^6.2.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run tests/unit",
+    "test:unit": "vitest run tests/unit",
+    "test:e2e": "vitest run tests/e2e",
+    "lint": "biome check .",
+    "format": "biome format --write ."
+  }
+}