@checkstack/integration-jira-common 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# @checkstack/integration-jira-common
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/common@0.0.2
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [a65e002]
+  - @checkstack/common@0.2.0
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+  - @checkstack/common@0.1.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@checkstack/integration-jira-common",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/common": "workspace:*",
+    "@orpc/contract": "^1.13.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// Plugin Metadata
+export { pluginMetadata } from "./plugin-metadata";
+
+// Schemas
+export {
+  // Legacy connection schemas (deprecated - use generic connection management)
+  JiraConnectionSchema,
+  type JiraConnection,
+  CreateJiraConnectionInputSchema,
+  type CreateJiraConnectionInput,
+  UpdateJiraConnectionInputSchema,
+  type UpdateJiraConnectionInput,
+  JiraConnectionRedactedSchema,
+  type JiraConnectionRedacted,
+  // API response schemas
+  JiraProjectSchema,
+  type JiraProject,
+  JiraIssueTypeSchema,
+  type JiraIssueType,
+  JiraFieldSchema,
+  type JiraField,
+  // Subscription config schemas
+  JiraFieldMappingSchema,
+  type JiraFieldMapping,
+  JiraSubscriptionConfigSchema,
+  type JiraSubscriptionConfig,
+} from "./schemas";
+
+// RPC Contract
+export { jiraContract, JiraApi, type JiraContract } from "./rpc-contract";

package/src/plugin-metadata.ts

@@ -0,0 +1,5 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "integration-jira",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,151 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  createClientDefinition,
+  type ProcedureMetadata,
+} from "@checkstack/common";
+import {
+  JiraConnectionRedactedSchema,
+  CreateJiraConnectionInputSchema,
+  UpdateJiraConnectionInputSchema,
+  JiraProjectSchema,
+  JiraIssueTypeSchema,
+  JiraFieldSchema,
+} from "./schemas";
+
+// Base builder with full metadata support
+const _base = oc.$meta<ProcedureMetadata>({});
+
+/**
+ * RPC contract for Jira-specific operations.
+ * These endpoints are in addition to the generic integration endpoints.
+ */
+export const jiraContract = {
+  // ==========================================================================
+  // CONNECTION MANAGEMENT (Site-wide Jira configurations)
+  // ==========================================================================
+
+  /** List all Jira connections (redacted - no API tokens) */
+  listConnections: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .output(z.array(JiraConnectionRedactedSchema)),
+
+  /** Get a single connection (redacted) */
+  getConnection: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .input(z.object({ id: z.string() }))
+    .output(JiraConnectionRedactedSchema),
+
+  /** Create a new Jira connection */
+  createConnection: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .input(CreateJiraConnectionInputSchema)
+    .output(JiraConnectionRedactedSchema),
+
+  /** Update a Jira connection */
+  updateConnection: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .input(UpdateJiraConnectionInputSchema)
+    .output(JiraConnectionRedactedSchema),
+
+  /** Delete a Jira connection */
+  deleteConnection: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  /** Test a Jira connection */
+  testConnection: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .input(z.object({ id: z.string() }))
+    .output(
+      z.object({
+        success: z.boolean(),
+        message: z.string().optional(),
+      })
+    ),
+
+  // ==========================================================================
+  // JIRA API PROXIES (Fetch data from Jira using a connection)
+  // ==========================================================================
+
+  /** Get projects available in a Jira connection */
+  getProjects: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .input(z.object({ connectionId: z.string() }))
+    .output(z.array(JiraProjectSchema)),
+
+  /** Get issue types available for a project */
+  getIssueTypes: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .input(
+      z.object({
+        connectionId: z.string(),
+        projectKey: z.string(),
+      })
+    )
+    .output(z.array(JiraIssueTypeSchema)),
+
+  /** Get fields available for a project and issue type */
+  getFields: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .input(
+      z.object({
+        connectionId: z.string(),
+        projectKey: z.string(),
+        issueTypeId: z.string(),
+      })
+    )
+    .output(z.array(JiraFieldSchema)),
+
+  /** Get priorities available in Jira */
+  getPriorities: _base
+    .meta({
+      userType: "user",
+      permissions: ["integration.manage"],
+    })
+    .input(z.object({ connectionId: z.string() }))
+    .output(
+      z.array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+          iconUrl: z.string().optional(),
+        })
+      )
+    ),
+};
+
+// Export contract type
+export type JiraContract = typeof jiraContract;
+
+// Export client definition for type-safe forPlugin usage
+export const JiraApi = createClientDefinition(jiraContract, pluginMetadata);

package/src/schemas.ts

@@ -0,0 +1,176 @@
+import { z } from "zod";
+
+// =============================================================================
+// Jira Connection (Site-wide Configuration) - DEPRECATED
+// Use the generic connection management system instead.
+// =============================================================================
+
+/**
+ * Schema for a Jira Cloud connection configuration.
+ * @deprecated Use generic connection management with JiraConnectionConfigSchema from jira-backend.
+ */
+export const JiraConnectionSchema = z.object({
+  /** Unique identifier for this connection */
+  id: z.string(),
+  /** User-friendly name for the connection */
+  name: z.string().min(1).max(100).describe("Connection name"),
+  /** Jira Cloud base URL (e.g., https://yourcompany.atlassian.net) */
+  baseUrl: z.string().url().describe("Jira Cloud base URL"),
+  /** Email address for authentication */
+  email: z.string().email().describe("Jira user email"),
+  /** API token - will be marked as secret in backend */
+  apiToken: z.string().min(1).describe("Jira API token"),
+  /** Created timestamp */
+  createdAt: z.coerce.date(),
+  /** Updated timestamp */
+  updatedAt: z.coerce.date(),
+});
+
+export type JiraConnection = z.infer<typeof JiraConnectionSchema>;
+
+/**
+ * Input for creating a new Jira connection.
+ */
+export const CreateJiraConnectionInputSchema = z.object({
+  name: z.string().min(1).max(100),
+  baseUrl: z.string().url(),
+  email: z.string().email(),
+  apiToken: z.string().min(1),
+});
+
+export type CreateJiraConnectionInput = z.infer<
+  typeof CreateJiraConnectionInputSchema
+>;
+
+/**
+ * Input for updating a Jira connection.
+ * API token is optional - if not provided, existing token is preserved.
+ */
+export const UpdateJiraConnectionInputSchema = z.object({
+  id: z.string(),
+  updates: z.object({
+    name: z.string().min(1).max(100).optional(),
+    baseUrl: z.string().url().optional(),
+    email: z.string().email().optional(),
+    /** If provided, replaces the existing token */
+    apiToken: z.string().min(1).optional(),
+  }),
+});
+
+export type UpdateJiraConnectionInput = z.infer<
+  typeof UpdateJiraConnectionInputSchema
+>;
+
+/**
+ * Redacted connection for frontend display (no API token).
+ */
+export const JiraConnectionRedactedSchema = JiraConnectionSchema.omit({
+  apiToken: true,
+});
+
+export type JiraConnectionRedacted = z.infer<
+  typeof JiraConnectionRedactedSchema
+>;
+
+// =============================================================================
+// Jira API Response Types
+// =============================================================================
+
+/**
+ * Jira project from the API.
+ */
+export const JiraProjectSchema = z.object({
+  id: z.string(),
+  key: z.string(),
+  name: z.string(),
+  avatarUrls: z.record(z.string(), z.string()).optional(),
+});
+
+export type JiraProject = z.infer<typeof JiraProjectSchema>;
+
+/**
+ * Jira issue type from the API.
+ */
+export const JiraIssueTypeSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().optional(),
+  iconUrl: z.string().optional(),
+  subtask: z.boolean(),
+});
+
+export type JiraIssueType = z.infer<typeof JiraIssueTypeSchema>;
+
+/**
+ * Jira field metadata from the API.
+ */
+export const JiraFieldSchema = z.object({
+  key: z.string(),
+  name: z.string(),
+  required: z.boolean(),
+  schema: z
+    .object({
+      type: z.string(),
+      system: z.string().optional(),
+      custom: z.string().optional(),
+      customId: z.number().optional(),
+    })
+    .optional(),
+  allowedValues: z
+    .array(
+      z.object({
+        id: z.string(),
+        name: z.string().optional(),
+        value: z.string().optional(),
+      })
+    )
+    .optional(),
+});
+
+export type JiraField = z.infer<typeof JiraFieldSchema>;
+
+// =============================================================================
+// Jira Subscription Configuration (Per-subscription)
+// =============================================================================
+
+/**
+ * Field mapping for template-based value population.
+ */
+export const JiraFieldMappingSchema = z.object({
+  /** Jira field key */
+  fieldKey: z.string(),
+  /** Template string with {{payload.property}} placeholders */
+  template: z.string(),
+});
+
+export type JiraFieldMapping = z.infer<typeof JiraFieldMappingSchema>;
+
+/**
+ * Provider configuration for Jira subscriptions.
+ */
+export const JiraSubscriptionConfigSchema = z.object({
+  /** ID of the site-wide Jira connection to use */
+  connectionId: z.string().describe("Jira connection to use"),
+  /** Jira project key to create issues in */
+  projectKey: z.string().describe("Project key"),
+  /** Issue type ID for created issues */
+  issueTypeId: z.string().describe("Issue type"),
+  /** Summary template (required - uses {{payload.field}} syntax) */
+  summaryTemplate: z.string().min(1).describe("Issue summary template"),
+  /** Description template (optional) */
+  descriptionTemplate: z
+    .string()
+    .optional()
+    .describe("Issue description template"),
+  /** Priority ID (optional) */
+  priorityId: z.string().optional().describe("Priority"),
+  /** Additional field mappings */
+  fieldMappings: z
+    .array(JiraFieldMappingSchema)
+    .optional()
+    .describe("Additional field mappings"),
+});
+
+export type JiraSubscriptionConfig = z.infer<
+  typeof JiraSubscriptionConfigSchema
+>;

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}