@shipeasy/devtools-core 1.0.0

package/dist/types-D0sroUDD.d.ts

@@ -0,0 +1,278 @@
+type UniverseParam = {
+    /**
+     * Param key, referenced by `groups[].params` on every experiment in the universe.
+     */
+    name: string;
+    /**
+     * Scalar type of the param's value.
+     */
+    type: 'bool' | 'string' | 'int' | 'number';
+    /**
+     * Universe-wide default. Returned when the assigned variant doesn't override this param (resolution: variant override → universe default).
+     */
+    default: unknown;
+};
+/**
+ * The universe's ordered config schema — the single source of truth for its params.
+ */
+type UniverseParamSchema = Array<UniverseParam>;
+type ListUniversesResponse = {
+    data: Array<{
+        /**
+         * Stable opaque universe id.
+         */
+        id: string;
+        /**
+         * Stable universe key. Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create.
+         */
+        name: string;
+        /**
+         * Human-readable blurb shown in the universe picker/hovercard.
+         */
+        description?: string | null;
+        /**
+         * Unit of randomisation. Snake-case in request (`unit_type`), camelCase in response.
+         */
+        unitType: string;
+        /**
+         * Reserved holdout bucket range, or `null` if none.
+         */
+        holdoutRange: [
+            number,
+            number
+        ] | null;
+        /**
+         * Basis points of headroom seeded into each new experiment's reserved tail (0 = none).
+         */
+        recommendedHeadroom?: number;
+        /**
+         * The universe-owned config schema, or `null` on pre-rework universes not yet seeded.
+         */
+        paramSchema?: UniverseParamSchema | null;
+        /**
+         * ISO-8601 timestamp of creation.
+         */
+        createdAt: string;
+    }>;
+    next_cursor: string | null;
+};
+
+/** Prod defaults; both overridable per client (local dev, staging). */
+declare const DEFAULT_ADMIN_BASE_URL = "https://shipeasy.ai";
+declare const DEFAULT_EDGE_BASE_URL = "https://api.shipeasy.ai";
+/** A completed device-auth login: the minted admin key + the project it binds. */
+interface DevtoolsSession {
+    /** Raw admin SDK key (`sdk_admin_*`). Store securely (Keychain/Keystore). */
+    token: string;
+    projectId: string;
+    userEmail: string | null;
+    projectName: string | null;
+}
+interface ProjectModules {
+    translations: boolean;
+    configs: boolean;
+    gates: boolean;
+    experiments: boolean;
+    feedback: boolean;
+    user: boolean;
+    events: boolean;
+}
+interface ProjectRecord {
+    id: string;
+    name: string;
+    domain: string | null;
+    modules: ProjectModules;
+}
+/** One attribute predicate inside a gate condition (e.g. `plan is one of
+ *  ["business"]`). Mirrors the admin `GateRule`. */
+interface GateRule {
+    attr: string;
+    op: string;
+    value: unknown;
+}
+/** One entry in a gate's ordered gatekeeper stack — evaluated top-to-bottom,
+ *  first match wins. A subset of the admin `StackedGateEntry` (the fields the
+ *  overlay renders). */
+interface GateStackEntry {
+    id?: string;
+    type?: "condition" | "rollout";
+    name?: string;
+    /** all rules must match ("all", default) vs any ("any"). */
+    pass?: "all" | "any";
+    rules?: GateRule[];
+    /** 0–10000 basis points. */
+    rolloutPct?: number;
+    bucketBy?: string;
+    locked?: boolean;
+    /** True when this condition is a whitelist (its rule's value is the list). */
+    whitelist?: boolean;
+}
+interface GateRecord {
+    id: string;
+    name: string;
+    enabled: boolean;
+    killswitch: boolean;
+    rolloutPct: number;
+    updatedAt: string;
+    /** Legacy flat targeting rules (pre-stack gates). */
+    rules?: GateRule[] | null;
+    /** The gatekeeper stack (modern gates). Present → drives the flow view. */
+    stack?: GateStackEntry[] | null;
+}
+/** Permissive default schema. Used when a config record arrives without one. */
+declare const PERMISSIVE_CONFIG_SCHEMA: Record<string, unknown>;
+interface ConfigRecord {
+    id: string;
+    name: string;
+    valueJson: unknown;
+    /** JSON Schema describing the value shape. Always type="object" post-migration. */
+    schema: Record<string, unknown>;
+    updatedAt: string;
+}
+/** One experiment variant (group): its label, split weight, and the per-variant
+ *  param overrides delivered when a caller is hashed into it (a subset of the
+ *  universe's param schema; unset keys inherit the universe default). */
+interface ExperimentVariant {
+    name: string;
+    /** Allocation weight in basis points (0–10000). */
+    weight: number;
+    params?: Record<string, unknown> | null;
+}
+interface ExperimentRecord {
+    id: string;
+    name: string;
+    /** Name of the universe this experiment runs in. */
+    universe: string;
+    status: "draft" | "running" | "stopped" | "archived";
+    groups: ExperimentVariant[];
+    updatedAt: string;
+    description?: string | null;
+    hypothesis?: string | null;
+    ownerEmail?: string | null;
+    audience?: string | null;
+    /** Unit of randomisation override, or null to inherit the universe's. */
+    bucketBy?: string | null;
+    /** Share of the gated audience allocated, in basis points (0–10000). */
+    allocationPct?: number;
+    /** ISO-8601 timestamp of the last transition to `running`, or null. */
+    startedAt?: string | null;
+    minSampleSize?: number;
+}
+interface ProfileRecord {
+    id: string;
+    name: string;
+    createdAt: string;
+    /** 1 when this is the project's default profile (D1 returns the int flag). */
+    isDefault?: number;
+}
+type UniverseRecord = ListUniversesResponse["data"][number];
+interface KeyRecord {
+    id: string;
+    key: string;
+    value: string;
+    profileId: string | null;
+    createdAt: string;
+}
+interface DraftRecord {
+    id: string;
+    name: string;
+    profileId: string;
+    status: string;
+    createdAt: string;
+}
+/** Subset of the server's `connector_data` the devtools read. The admin
+ *  endpoints return the full blob; we only type the fields the overlays render:
+ *  the linked GitHub issue/PR (with the PR's merged marker), and the agent
+ *  trace Jarvis records as it works an item. All fields are tolerated absent. */
+interface FeedbackConnectorData {
+    github?: {
+        issue?: {
+            number: number;
+            url: string;
+        };
+        pr?: {
+            number: number;
+            url: string;
+            /** Merged markers — any of these present means the PR landed. */
+            merged?: boolean;
+            mergedAt?: string | null;
+            state?: string;
+        };
+    };
+    /** Agent (Jarvis) trace — present once the AI has acted on the item.
+     *  `awaitingReply` / `state: "awaiting_reply"` means it posted a question
+     *  back and is waiting on a human. */
+    agent?: {
+        state?: string;
+        awaitingReply?: boolean;
+    };
+}
+type BugStatus = "open" | "pending_approval" | "triaged" | "in_progress" | "ready_for_qa" | "resolved" | "wont_fix";
+/** Lowest tier is `nice_to_have`; shared by bugs + feature requests. */
+type BugPriority = "nice_to_have" | "medium" | "high" | "critical";
+interface BugRecord {
+    id: string;
+    title: string;
+    status: BugStatus;
+    priority: BugPriority | null;
+    reporterEmail: string | null;
+    pageUrl: string | null;
+    createdAt: string;
+    connectorData?: FeedbackConnectorData | null;
+}
+interface AttachmentRecord {
+    id: string;
+    kind: "screenshot" | "recording" | "file";
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    createdAt: string;
+}
+interface BugDetail extends BugRecord {
+    stepsToReproduce: string;
+    actualResult: string;
+    expectedResult: string;
+    attachments: AttachmentRecord[];
+}
+/** The queue-item type. `bug`/`feature_request` are user-fileable; `error` and
+ *  `alert` are auto-filed system tickets the overlay now also lists. */
+type OpsItemType = "bug" | "feature_request" | "error" | "alert" | "measure_plan";
+/** Generic ops-item detail — the enriched GET response, permissive across all
+ *  types (bug/feature content fields present only for those types; empty for
+ *  auto-filed error/alert tickets). */
+interface OpsItemDetail extends BugRecord {
+    type?: OpsItemType;
+    /** Auto-filed tickets carry the originating record's key (error fingerprint,
+     *  alert dedupe key), or null for human-filed bugs/features. */
+    sourceRef?: string | null;
+    stepsToReproduce?: string;
+    actualResult?: string;
+    expectedResult?: string;
+    description?: string;
+    useCase?: string;
+    attachments: AttachmentRecord[];
+}
+interface FeatureRequestRecord {
+    id: string;
+    title: string;
+    status: BugStatus;
+    priority: BugPriority | null;
+    reporterEmail: string | null;
+    pageUrl: string | null;
+    createdAt: string;
+    connectorData?: FeedbackConnectorData | null;
+}
+interface FeatureRequestDetail extends FeatureRequestRecord {
+    description: string;
+    useCase: string;
+    attachments: AttachmentRecord[];
+}
+interface AttachmentUploadResult {
+    id: string;
+    filename: string;
+    kind: "screenshot" | "recording" | "file";
+    mimeType: string;
+    sizeBytes: number;
+}
+
+export { type AttachmentRecord as A, type BugDetail as B, type ConfigRecord as C, DEFAULT_ADMIN_BASE_URL as D, type ExperimentRecord as E, type FeatureRequestDetail as F, type GateRecord as G, type KeyRecord as K, type OpsItemDetail as O, PERMISSIVE_CONFIG_SCHEMA as P, type UniverseRecord as U, type AttachmentUploadResult as a, type BugPriority as b, type BugRecord as c, type BugStatus as d, DEFAULT_EDGE_BASE_URL as e, type DevtoolsSession as f, type DraftRecord as g, type FeatureRequestRecord as h, type FeedbackConnectorData as i, type GateRule as j, type GateStackEntry as k, type OpsItemType as l, type ProfileRecord as m, type ProjectModules as n, type ProjectRecord as o };

package/dist/zod.gen-DTKpgw-T.d.mts

@@ -0,0 +1,64 @@
+import * as z from 'zod';
+
+/**
+ * Bug-kind fields for `POST /api/admin/ops` (sent with `type: bug`).
+ */
+declare const zCreateBugRequest: z.ZodObject<{
+    type: z.ZodEnum<{
+        bug: "bug";
+    }>;
+    title: z.ZodString;
+    stepsToReproduce: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    actualResult: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    expectedResult: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    priority: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        nice_to_have: "nice_to_have";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>>>;
+    reporterEmail: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    pageUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
+    userAgent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    viewport: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    context: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    notify: z.ZodOptional<z.ZodNullable<z.ZodNullable<z.ZodObject<{
+        slackChannel: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type CreateBugRequestInput = z.infer<typeof zCreateBugRequest>;
+/**
+ * Feature-request-kind fields for `POST /api/admin/ops` (sent with `type: feature_request`).
+ */
+declare const zCreateFeatureRequestRequest: z.ZodObject<{
+    type: z.ZodEnum<{
+        feature_request: "feature_request";
+    }>;
+    title: z.ZodString;
+    description: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    useCase: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    priority: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        nice_to_have: "nice_to_have";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>>>;
+    reporterEmail: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    pageUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
+    userAgent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    context: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    notify: z.ZodOptional<z.ZodNullable<z.ZodNullable<z.ZodObject<{
+        slackChannel: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type CreateFeatureRequestRequestInput = z.infer<typeof zCreateFeatureRequestRequest>;
+
+export { type CreateBugRequestInput as C, type CreateFeatureRequestRequestInput as a, zCreateFeatureRequestRequest as b, zCreateBugRequest as z };

package/dist/zod.gen-DTKpgw-T.d.ts

@@ -0,0 +1,64 @@
+import * as z from 'zod';
+
+/**
+ * Bug-kind fields for `POST /api/admin/ops` (sent with `type: bug`).
+ */
+declare const zCreateBugRequest: z.ZodObject<{
+    type: z.ZodEnum<{
+        bug: "bug";
+    }>;
+    title: z.ZodString;
+    stepsToReproduce: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    actualResult: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    expectedResult: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    priority: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        nice_to_have: "nice_to_have";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>>>;
+    reporterEmail: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    pageUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
+    userAgent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    viewport: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    context: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    notify: z.ZodOptional<z.ZodNullable<z.ZodNullable<z.ZodObject<{
+        slackChannel: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type CreateBugRequestInput = z.infer<typeof zCreateBugRequest>;
+/**
+ * Feature-request-kind fields for `POST /api/admin/ops` (sent with `type: feature_request`).
+ */
+declare const zCreateFeatureRequestRequest: z.ZodObject<{
+    type: z.ZodEnum<{
+        feature_request: "feature_request";
+    }>;
+    title: z.ZodString;
+    description: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    useCase: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    priority: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        nice_to_have: "nice_to_have";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>>>;
+    reporterEmail: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    pageUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
+    userAgent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    context: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    notify: z.ZodOptional<z.ZodNullable<z.ZodNullable<z.ZodObject<{
+        slackChannel: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type CreateFeatureRequestRequestInput = z.infer<typeof zCreateFeatureRequestRequest>;
+
+export { type CreateBugRequestInput as C, type CreateFeatureRequestRequestInput as a, zCreateFeatureRequestRequest as b, zCreateBugRequest as z };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@shipeasy/devtools-core",
+  "version": "1.0.0",
+  "description": "Headless core for the Shipeasy devtools overlays \u2014 admin API client, PKCE device auth, public bug intake, form schemas.",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://shipeasy.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shipeasy-ai/sdk-ts.git",
+    "directory": "packages/devtools-core"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.mjs",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "gen:devtools": "openapi-ts",
+    "refresh:spec": "node scripts/refresh-devtools-spec.mjs"
+  },
+  "peerDependencies": {
+    "@shipeasy/sdk": ">=8.0.0",
+    "zod": ">=4"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.99.0",
+    "@shipeasy/sdk": "workspace:*",
+    "@types/node": "^26.0.1",
+    "tsup": "^8.3.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}