@ninedeploy/schemas 0.10.5 → 0.16.0

package/src/githubApp.ts

@@ -0,0 +1,268 @@
+import { z } from 'zod';
+import { id, providerBaseUrl } from './common.js';
+import { webhookCreate } from './management.js';
+
+// ── GitHub App (0.13) ──────────────────────────────────────────────────────
+// Request and response shapes for `/v1/github-apps/*` and
+// `/v1/services/:id/github*`. Secrets (private key, webhook secret, client
+// secret) only ever appear in REQUEST shapes; no response shape has a field
+// that could carry one.
+
+export const GITHUB_WEB_BASE_URL = 'https://github.com';
+export const GITHUB_API_BASE_URL = 'https://api.github.com';
+
+/** Mirrors `githubTokenScope` in `@ninedeploy/db`. */
+export const githubTokenScope = z.enum(['repository', 'installation']);
+export type GithubTokenScope = z.infer<typeof githubTokenScope>;
+
+/** Mirrors `githubRepositorySelection` in `@ninedeploy/db`. */
+export const githubRepositorySelection = z.enum(['all', 'selected']);
+
+/**
+ * A numeric GitHub id (App, installation, repository, account). GitHub ids
+ * are positive and well below 2^53; `int()` keeps them safe integers.
+ */
+export const githubNumericId = z.number().int().positive();
+
+/**
+ * A GitHub user or organization login. It is interpolated into the manifest
+ * `postUrl` path, so the character set is pinned to GitHub's own rule
+ * (alphanumerics and single inner hyphens, at most 39 characters).
+ */
+export const githubLogin = z
+  .string()
+  .trim()
+  .regex(/^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/, 'invalid GitHub login');
+
+/** `owner/repo`, as GitHub reports `full_name`. */
+export const githubRepoFullName = z
+  .string()
+  .max(200)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/, 'expected owner/repo');
+
+/**
+ * A PEM-encoded private key as GitHub hands it out (PKCS#1 `RSA PRIVATE KEY`)
+ * or re-encoded as PKCS#8 (`PRIVATE KEY`). This is a shape check only; the
+ * server proves the key by signing a JWT and calling `GET /app`.
+ */
+export const githubPrivateKeyPem = z
+  .string()
+  .trim()
+  .max(16384)
+  .regex(
+    /^-----BEGIN (RSA )?PRIVATE KEY-----\r?\n[\s\S]+\r?\n-----END \1PRIVATE KEY-----$/,
+    'privateKey must be a PEM private key (-----BEGIN RSA PRIVATE KEY-----)',
+  );
+
+const appName = z.string().trim().min(1).max(100);
+const secretText = z.string().min(1).max(1024);
+const clientId = z.string().trim().min(1).max(255);
+
+const atLeastOneField = (value: Record<string, unknown>): boolean =>
+  Object.values(value).some((v) => v !== undefined);
+
+// ── Manifest flow ──────────────────────────────────────────────────────────
+
+/**
+ * POST /v1/github-apps/manifest. `org` is required for an organization-owned
+ * App and refused for a personal one. `apiBaseUrl` may be omitted: the server
+ * derives it (`https://api.github.com` for github.com, `<web>/api/v3` for
+ * GitHub Enterprise Server).
+ */
+export const githubAppManifestRequest = z
+  .object({
+    target: z.enum(['user', 'org']),
+    org: githubLogin.optional(),
+    webBaseUrl: providerBaseUrl.default(GITHUB_WEB_BASE_URL),
+    apiBaseUrl: providerBaseUrl.optional(),
+    /** Also request `checks: write` (the Checks API itself is not used in 0.13). */
+    checks: z.boolean().default(false),
+  })
+  .refine((v) => v.target !== 'org' || v.org !== undefined, {
+    message: 'org is required when target is "org"',
+    path: ['org'],
+  })
+  .refine((v) => v.target !== 'user' || v.org === undefined, {
+    message: 'org is only valid when target is "org"',
+    path: ['org'],
+  });
+export type GithubAppManifestRequest = z.input<typeof githubAppManifestRequest>;
+
+/** The SPA submits `manifest` (JSON-encoded) as a form field to `postUrl`. */
+export const githubAppManifestResponse = z.object({
+  postUrl: z.string(),
+  manifest: z.record(z.string(), z.unknown()),
+  state: z.string(),
+});
+export type GithubAppManifestResponse = z.infer<typeof githubAppManifestResponse>;
+
+/**
+ * POST /v1/github-apps/manifest/complete. `code` is interpolated into
+ * `/app-manifests/<code>/conversions`, so it is restricted to URL-path-safe
+ * characters.
+ */
+export const githubAppManifestComplete = z.object({
+  code: z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[A-Za-z0-9_-]+$/, 'invalid manifest code'),
+  state: z.string().min(1).max(4096),
+});
+export type GithubAppManifestComplete = z.infer<typeof githubAppManifestComplete>;
+
+// ── Manual entry (GHES or an existing App) ─────────────────────────────────
+
+/**
+ * POST /v1/github-apps. Omit both base URLs for github.com; for GitHub
+ * Enterprise Server give both. Giving only one is refused, so a GHES App's JWT
+ * is never sent to api.github.com by default. An omitted `webhookSecret` is
+ * generated by the server and registered on the App.
+ */
+export const githubAppCreate = z
+  .object({
+    name: appName,
+    appId: githubNumericId,
+    privateKey: githubPrivateKeyPem,
+    webhookSecret: secretText.optional(),
+    clientId: clientId.optional(),
+    clientSecret: secretText.optional(),
+    webBaseUrl: providerBaseUrl.optional(),
+    apiBaseUrl: providerBaseUrl.optional(),
+  })
+  .refine((v) => (v.webBaseUrl === undefined) === (v.apiBaseUrl === undefined), {
+    message: 'webBaseUrl and apiBaseUrl go together; omit both for github.com',
+    path: ['apiBaseUrl'],
+  })
+  .transform((v) => ({
+    ...v,
+    webBaseUrl: v.webBaseUrl ?? GITHUB_WEB_BASE_URL,
+    apiBaseUrl: v.apiBaseUrl ?? GITHUB_API_BASE_URL,
+  }));
+export type GithubAppCreate = z.input<typeof githubAppCreate>;
+
+/** PATCH /v1/github-apps/:id. `null` clears the optional OAuth client fields. */
+export const githubAppPatch = z
+  .object({
+    name: appName.optional(),
+    clientId: clientId.nullable().optional(),
+    clientSecret: secretText.nullable().optional(),
+  })
+  .refine(atLeastOneField, { message: 'nothing to update' });
+export type GithubAppPatch = z.infer<typeof githubAppPatch>;
+
+/** PUT /v1/github-apps/:id/private-key. */
+export const githubAppPrivateKey = z.object({ privateKey: githubPrivateKeyPem });
+export type GithubAppPrivateKey = z.infer<typeof githubAppPrivateKey>;
+
+// ── Views (responses: metadata only, never a secret) ───────────────────────
+
+export const githubApp = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  appId: z.number().int(),
+  slug: z.string().nullable(),
+  clientId: z.string().nullable(),
+  ownerLogin: z.string().nullable(),
+  ownerType: z.string().nullable(),
+  webBaseUrl: z.string(),
+  apiBaseUrl: z.string(),
+  htmlUrl: z.string().nullable(),
+  permissions: z.record(z.string(), z.string()).nullable(),
+  events: z.array(z.string()).nullable(),
+  /** Where GitHub delivers this App's webhooks (`/v1/hooks/github-app/<key>`). */
+  webhookUrl: z.string(),
+  /** `${htmlUrl}/installations/new`; null until the App's html URL is known. */
+  installUrl: z.string().nullable(),
+  hasPrivateKey: z.boolean(),
+  hasClientSecret: z.boolean(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type GithubApp = z.infer<typeof githubApp>;
+
+export const githubAppInstallation = z.object({
+  id: z.number().int(),
+  githubAppId: z.number().int(),
+  installationId: z.number().int(),
+  accountLogin: z.string().nullable(),
+  accountType: z.string().nullable(),
+  accountId: z.number().int().nullable(),
+  repositorySelection: githubRepositorySelection,
+  permissions: z.record(z.string(), z.string()).nullable(),
+  /** The generated `github_app` source; null once that source was deleted. */
+  sourceId: z.number().int().nullable(),
+  suspendedAt: z.string().nullable(),
+  removedAt: z.string().nullable(),
+  /** GitHub's settings page for this installation. */
+  configureUrl: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type GithubAppInstallation = z.infer<typeof githubAppInstallation>;
+
+// ── Service ↔ repository link ──────────────────────────────────────────────
+
+const linkWatchPaths = webhookCreate.shape.watchPaths.unwrap();
+
+/**
+ * PUT /v1/services/:id/github (operator). `sourceId` is a `github_app` source
+ * and so names the installation. `repoId` may be omitted; the server then
+ * resolves it from the service's repository URL. `tokenScope` widens clone
+ * tokens to the whole installation (sibling-repo submodules), so it lives on
+ * this operator route and not on the admin feedback PATCH.
+ */
+export const serviceGithubLinkPut = z.object({
+  sourceId: id,
+  repoId: githubNumericId.optional(),
+  tokenScope: githubTokenScope.optional(),
+  /** Newline/comma-separated globs (same rules as a webhook); null clears. */
+  watchPaths: linkWatchPaths.nullable().optional(),
+  enabled: z.boolean().optional(),
+});
+export type ServiceGithubLinkPut = z.infer<typeof serviceGithubLinkPut>;
+
+/** PATCH /v1/services/:id/github/feedback (admin). Both default to off. */
+export const serviceGithubFeedbackPatch = z
+  .object({
+    /** Post commit statuses (`ninedeploy/<slug>`) for deploys. */
+    reportStatus: z.boolean().optional(),
+    /** Upsert one comment per PR with the preview URL and outcome. */
+    prComment: z.boolean().optional(),
+  })
+  .refine(atLeastOneField, { message: 'nothing to update' });
+export type ServiceGithubFeedbackPatch = z.infer<typeof serviceGithubFeedbackPatch>;
+
+/**
+ * POST /v1/services/:id/github/migrate (operator). Links the service to the
+ * App installation behind `sourceId`, remembering the current source as
+ * `previousSourceId`; the service's own source and webhook are left as is.
+ */
+export const serviceGithubMigrate = z.object({ sourceId: id });
+export type ServiceGithubMigrate = z.infer<typeof serviceGithubMigrate>;
+
+/** GET /v1/services/:id/github → `{ link }`, `link` null when unlinked. */
+export const serviceGithubLink = z.object({
+  id: z.number().int(),
+  serviceId: z.number().int(),
+  installationRowId: z.number().int(),
+  githubAppId: z.number().int(),
+  /** The installation's `github_app` source, when it still exists. */
+  sourceId: z.number().int().nullable(),
+  repoId: z.number().int(),
+  repoFullName: z.string(),
+  enabled: z.boolean(),
+  tokenScope: githubTokenScope,
+  watchPaths: z.string().nullable(),
+  reportStatus: z.boolean(),
+  prComment: z.boolean(),
+  previousSourceId: z.number().int().nullable(),
+  /** Enabled AND the installation is neither suspended nor removed: the App drives deploys. */
+  active: z.boolean(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type ServiceGithubLink = z.infer<typeof serviceGithubLink>;
+
+export const serviceGithubStatus = z.object({ link: serviceGithubLink.nullable() });
+export type ServiceGithubStatus = z.infer<typeof serviceGithubStatus>;

package/src/index.ts

@@ -0,0 +1,30 @@
+export * from './common.js';
+export * from './auth.js';
+export * from './management.js';
+export * from './ninedeployManifest.js';
+export type { AlertWhen } from './ninedeployManifest.js';
+export type { RestartPolicy } from './ninedeployManifest.js';
+export * from './project.js';
+export * from './service.js';
+export * from './insights.js';
+export * from './kernel.js';
+export * from './workspaces.js';
+export * from './labels.js';
+export * from './environments.js';
+export * from './ai.js';
+export * from './secretScan.js';
+export * from './runtimeVersions.js';
+export * from './doctor.js';
+export * from './agentCommand.js';
+
+export * from './backupPolicy.js';
+export * from './panelBackup.js';
+export * from './githubApp.js';
+export * from './publicAccess.js';
+export * from './proxyConfig.js';
+export * from './databaseImport.js';
+export * from './secretProviders.js';
+export * from './terminals.js';
+export * from './traffic.js';
+export * from './accessGrants.js';
+export * from './multiNode.js';

package/src/insights.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { gitBranch, gitRepoUrl, repoBaseDir } from './common.js';
+
+// ── Repository / framework insights ─────────────────────────────────────────
+// The analysis engine (server lib/frameworks.ts) inspects a checked-out repo
+// and reduces it to this shape; the wizard and the service-detail Framework
+// tab render it to explain "what is in this repo and how should it deploy".
+
+export const frameworkCategory = z.enum(['ssr', 'spa', 'static', 'backend', 'container', 'unknown']);
+export type FrameworkCategory = z.infer<typeof frameworkCategory>;
+
+export const packageManagerId = z.enum(['npm', 'pnpm', 'yarn', 'bun']);
+export type PackageManagerId = z.infer<typeof packageManagerId>;
+
+/** One recommended environment variable (pre-filled, user-editable). */
+export const envSuggestion = z.object({
+  key: z.string(),
+  value: z.string(),
+  description: z.string().optional(),
+});
+export type EnvSuggestion = z.infer<typeof envSuggestion>;
+
+/** A detected framework plus its deploy preset (commands already adapted to
+ * the detected package manager). Null commands mean "no safe suggestion". */
+export const frameworkPreset = z.object({
+  id: z.string(),
+  name: z.string(),
+  emoji: z.string(),
+  category: frameworkCategory,
+  port: z.number().int().min(1).max(65535),
+  installCmd: z.string().nullable(),
+  buildCmd: z.string().nullable(),
+  startCmd: z.string().nullable(),
+  env: z.array(envSuggestion),
+  notes: z.array(z.string()),
+});
+export type FrameworkPreset = z.infer<typeof frameworkPreset>;
+
+export const repoInsights = z.object({
+  framework: frameworkPreset,
+  language: z.string(),
+  packageManager: packageManagerId.nullable(),
+  nodeVersion: z.string().nullable(),
+  frameworkVersion: z.string().nullable(),
+  scripts: z.record(z.string(), z.string()),
+  dependencyCount: z.number().int(),
+  devDependencyCount: z.number().int(),
+  hasDockerfile: z.boolean(),
+  hasComposeFile: z.boolean(),
+  monorepo: z.boolean(),
+  /** Marker files the detection was derived from (e.g. package.json, go.mod). */
+  detectedFiles: z.array(z.string()),
+  /** Workspace member packages of a monorepo root (empty for single-app repos
+   * and for analyses scoped to a base directory). Powers the wizard's
+   * "deploy each sub-app as its own service" picker. */
+  workspacePackages: z.array(
+    z.object({
+      /** Repo-relative directory, e.g. "apps/web". */
+      dir: z.string(),
+      name: z.string().nullable(),
+      framework: z.string().nullable(),
+      frameworkVersion: z.string().nullable(),
+    }),
+  ),
+  baseDir: z.string(),
+  commitSha: z.string().nullable().optional(),
+  analyzedAt: z.string().datetime(),
+});
+export type RepoInsights = z.infer<typeof repoInsights>;
+
+/** Pre-deploy inspection request (DeployWizard, before a service exists). */
+export const analyzeRepoInput = z.object({
+  repoUrl: gitRepoUrl,
+  branch: gitBranch.default('main'),
+  sourceId: z.number().int().positive().optional(),
+  baseDir: repoBaseDir.optional(),
+});
+export type AnalyzeRepoInput = z.input<typeof analyzeRepoInput>;

package/src/kernel.ts

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+
+// ─── Configuration Center Schemas ───────────────────────────────────────────
+export const configItemSchema = z.object({
+  key: z.string(),
+  pluginId: z.string().nullable().optional(),
+  type: z.enum(['string', 'number', 'boolean', 'enum', 'json']).default('string'),
+  isSecret: z.boolean(),
+  label: z.string(),
+  category: z.string(),
+  description: z.string().optional(),
+  tags: z.array(z.string()),
+  options: z.array(z.string()).optional(),
+  value: z.unknown(),
+  isConfigured: z.boolean(),
+  updatedAt: z.string().optional(),
+});
+export type ConfigItem = z.infer<typeof configItemSchema>;
+
+export const configListSchema = z.object({
+  entries: z.array(configItemSchema),
+});
+export type ConfigListResponse = z.infer<typeof configListSchema>;
+
+export const setConfigSchema = z.object({
+  // Optional: an omitted value keeps the current one (metadata-only update).
+  value: z.unknown().optional(),
+  isSecret: z.boolean().optional(),
+  description: z.string().max(500).optional(),
+  tags: z.array(z.string().max(50)).optional(),
+});
+export type SetConfigInput = z.infer<typeof setConfigSchema>;
+
+// ─── Plugin Ecosystem Schemas ───────────────────────────────────────────────
+export const pluginItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  version: z.string(),
+  description: z.string().optional(),
+  author: z.string().optional(),
+  icon: z.string().optional(),
+  isOfficial: z.boolean(),
+  enabled: z.boolean(),
+  status: z.enum(['active', 'disabled', 'errored', 'installing']),
+  configSchema: z.array(z.record(z.string(), z.unknown())).optional(),
+  menuItems: z.array(z.record(z.string(), z.unknown())).optional(),
+  dependencies: z.array(z.string()).optional(),
+  error: z.string().optional(),
+  /**
+   * r600: sandbox plugins only — false when this Node's permission model has
+   * no network scope (Node < 25) and the plugin can open sockets / fetch.
+   */
+  networkRestricted: z.boolean().optional(),
+  installedAt: z.string().optional(),
+});
+export type PluginItem = z.infer<typeof pluginItemSchema>;
+
+export const pluginListSchema = z.object({
+  plugins: z.array(pluginItemSchema),
+});
+export type PluginListResponse = z.infer<typeof pluginListSchema>;
+
+export const installPluginSchema = z.object({
+  source: z.enum(['marketplace', 'npm', 'git', 'local', 'sandbox']).default('marketplace'),
+  target: z.string().min(1),
+  name: z.string().optional(),
+  version: z.string().optional(),
+  description: z.string().optional(),
+  author: z.string().optional(),
+  icon: z.string().optional(),
+  dependencies: z.array(z.string()).optional(),
+  configSchema: z.array(z.record(z.string(), z.unknown())).optional(),
+  menuItems: z.array(z.record(z.string(), z.unknown())).optional(),
+  /**
+   * Sandbox-source only: the worker script the plugin runs. This field (and
+   * `manifest`) MUST travel with the install — a sandbox plugin installed
+   * without its code used to register as "active" while silently executing
+   * nothing, and after a restart the restored row had no way to reload the
+   * code at all. Bounded so one install cannot balloon the SQLite row.
+   */
+  code: z.string().min(1).max(256 * 1024).optional(),
+  manifest: z.record(z.string(), z.unknown()).optional(),
+});
+export type InstallPluginInput = z.infer<typeof installPluginSchema>;
+
+export const marketplacePluginItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  version: z.string(),
+  description: z.string(),
+  author: z.string(),
+  icon: z.string().optional(),
+  category: z.string(),
+  isOfficial: z.boolean(),
+  isInstalled: z.boolean().default(false),
+  /**
+   * Whether installing this entry actually does anything.
+   *
+   * NineDeploy does not load third-party plugin code, so every catalog entry is
+   * a roadmap item until the behaviour is compiled into the server. Marking it
+   * matters because several entries shadow features that already exist by
+   * another name — an operator who "installed" the S3 sync plugin, filled in a
+   * bucket and secret key, and saw it reported as active would reasonably
+   * believe their backups were being copied off-site. They were not.
+   */
+  implemented: z.boolean().default(false),
+  /** Where the real feature lives, for entries that shadow a shipped one. */
+  builtIn: z
+    .object({
+      label: z.string(),
+      /** Panel route, e.g. `/settings?tab=storage`. */
+      path: z.string(),
+    })
+    .optional(),
+  dependencies: z.array(z.string()).optional(),
+  configSchema: z.array(z.record(z.string(), z.unknown())).optional(),
+  menuItems: z.array(z.record(z.string(), z.unknown())).optional(),
+});
+export type MarketplacePluginItem = z.infer<typeof marketplacePluginItemSchema>;
+
+export const marketplaceCatalogSchema = z.object({
+  catalog: z.array(marketplacePluginItemSchema),
+  /** True when the live signed index was reached and
+   *  verified; false when the upstream was unreachable
+   *  and the static catalog was served. */
+  live: z.boolean().default(false),
+  /** The verifying key id, when the live index was used. */
+  keyId: z.string().nullable().optional(),
+  /** When the cache was last refreshed (ms since epoch). */
+  fetchedAt: z.number().optional(),
+});
+export type MarketplaceCatalogResponse = z.infer<typeof marketplaceCatalogSchema>;
+
+// ─── Menu & Navigation Schemas ──────────────────────────────────────────────
+export const menuItemSchema = z.object({
+  id: z.string(),
+  pluginId: z.string().optional(),
+  slot: z.string(),
+  label: z.string(),
+  route: z.string(),
+  icon: z.string().optional(),
+  order: z.number().optional(),
+  permission: z.enum(['admin', 'member']).optional(),
+});
+export type MenuItem = z.infer<typeof menuItemSchema>;
+
+export const menuListSchema = z.object({
+  slots: z.record(z.string(), z.array(menuItemSchema)),
+  items: z.array(menuItemSchema),
+});
+export type MenuListResponse = z.infer<typeof menuListSchema>;
+
+export const pluginInspectSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  version: z.string(),
+  description: z.string().optional(),
+  author: z.string().optional(),
+  isOfficial: z.boolean(),
+  enabled: z.boolean(),
+  status: z.enum(['active', 'disabled', 'errored', 'installing']),
+  dependencies: z.array(z.string()),
+  hooks: z.array(z.string()),
+  services: z.array(z.string()),
+  menus: z.array(menuItemSchema),
+  configSchema: z.array(z.record(z.string(), z.unknown())),
+  error: z.string().nullable().optional(),
+  /** r600: see pluginItemSchema.networkRestricted. */
+  networkRestricted: z.boolean().optional(),
+  installedAt: z.string().optional(),
+  runtimeStats: z.object({
+    /** null = not tracked per plugin by the kernel (r286: was a hard-coded 42). */
+    eventsHandled: z.number().nullable(),
+    /** null = not tracked per plugin by the kernel (r286: was a hard-coded 3600). */
+    uptimeSeconds: z.number().nullable(),
+    loadedAt: z.string().optional(),
+  }),
+});
+export type PluginInspectResponse = z.infer<typeof pluginInspectSchema>;
+

package/src/labels.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+
+/**
+ * Workspace-scoped free-form labels used to tag services without tying them
+ * to the project hierarchy (e.g. "production", "staging", "team-x"). Labels
+ * can be created on the fly; the color is a tailwind-style palette token
+ * consumed by the UI.
+ */
+export const labelColor = z.enum([
+  'indigo',
+  'emerald',
+  'amber',
+  'rose',
+  'sky',
+  'slate',
+  'violet',
+  'lime',
+]);
+export type LabelColor = z.infer<typeof labelColor>;
+
+export const createLabel = z.object({
+  workspaceId: z.number().int().positive().nullable().optional(),
+  name: z.string().trim().min(1).max(40),
+  color: labelColor.default('indigo'),
+});
+export type CreateLabel = z.infer<typeof createLabel>;
+export type CreateLabelInput = CreateLabel;
+
+export const labelPatch = z
+  .object({
+    name: z.string().trim().min(1).max(40).optional(),
+    color: labelColor.optional(),
+  })
+  .refine((v) => Object.keys(v).length > 0, { message: 'nothing to update' });
+export type LabelPatch = z.infer<typeof labelPatch>;
+export type LabelPatchInput = LabelPatch;
+
+export const label = z.object({
+  id: z.number().int(),
+  workspaceId: z.number().int().nullable(),
+  name: z.string(),
+  color: z.string(),
+  serviceCount: z.number().int().nonnegative(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+export type Label = z.infer<typeof label>;
+
+/**
+ * PUT /v1/services/:id/tags body — replaces the service's project / workspace
+ * / label memberships wholesale. The caller must be a member of every
+ * workspace in `workspaceIds` (or an operator), and every project/label id
+ * must be valid. Empty arrays clear the corresponding dimension.
+ */
+export const setServiceTags = z.object({
+  projectIds: z.array(z.number().int().positive()).default([]),
+  workspaceIds: z.array(z.number().int().positive()).default([]),
+  labelIds: z.array(z.number().int().positive()).default([]),
+});
+export type SetServiceTags = z.infer<typeof setServiceTags>;
+export type SetServiceTagsInput = SetServiceTags;
+
+export const serviceTags = z.object({
+  serviceId: z.number().int(),
+  projects: z.array(z.object({ id: z.number().int(), name: z.string(), slug: z.string() })),
+  workspaces: z.array(z.object({ id: z.number().int(), name: z.string(), slug: z.string() })),
+  labels: z.array(z.object({ id: z.number().int(), name: z.string(), color: z.string() })),
+});
+export type ServiceTags = z.infer<typeof serviceTags>;
+
+/**
+ * /v1/services list filter — every present array is OR'd within its dimension
+ * and AND'd across dimensions. An empty array means "no filter on this
+ * dimension" (so omitting all three is equivalent to the unfiltered list).
+ *
+ *   ?tagWorkspaceIds=1,2   → service is in ws 1 OR ws 2
+ *   ?tagProjectIds=10      → service has project 10
+ *   ?tagLabelIds=3,4       → service has label 3 OR 4
+ *   combined: AND across dimensions
+ */
+export const serviceListFilter = z.object({
+  tagWorkspaceIds: z.array(z.number().int().positive()).default([]),
+  tagProjectIds: z.array(z.number().int().positive()).default([]),
+  tagLabelIds: z.array(z.number().int().positive()).default([]),
+});
+export type ServiceListFilter = z.infer<typeof serviceListFilter>;