@useairfoil/producer-linear 0.0.0-stage → 0.0.2

package/src/schemas/teams.ts

@@ -0,0 +1,144 @@
+import { Iceberg } from "@useairfoil/connector-kit";
+import { Schema, Struct } from "effect";
+
+import {
+  OptionalRef,
+  OptionalString,
+  OptionalTimestamp,
+  Ref,
+  Timestamp,
+  common,
+  deleted,
+  field,
+} from "./shared";
+
+export const TeamSchema = Schema.Struct({
+  ...common("Team"),
+  name: Schema.String.pipe(field(10, "Team name.")),
+  key: Schema.String.pipe(field(11, "Team key, used in issue IDs such as ENG-123.")),
+  display_name: Schema.String.pipe(field(12, "Name shown in Linear.")),
+  description: OptionalString.pipe(field(13, "Team description.")),
+  visibility: Schema.String.pipe(field(14, "Who can see the team.")),
+  parent_id: OptionalRef.pipe(field(15, "Parent team.")),
+  timezone: Schema.String.pipe(field(16, "Team timezone.")),
+  cycles_enabled: Schema.Boolean.pipe(field(17, "Whether the team uses cycles.")),
+  cycle_duration: Schema.Finite.pipe(field(18, "Cycle length in weeks.")),
+  cycle_cooldown_time: Schema.Finite.pipe(field(19, "Weeks between cycles.")),
+  cycle_start_day: Schema.Finite.pipe(field(20, "Day cycles start, 0 for Sunday.")),
+  triage_enabled: Schema.Boolean.pipe(field(21, "Whether the team uses triage.")),
+  issue_estimation_type: Schema.String.pipe(field(22, "Estimate scale.")),
+  default_issue_estimate: Schema.Finite.pipe(field(23, "Default estimate.")),
+  auto_archive_period: Schema.Finite.pipe(field(24, "Months before closed issues are archived.")),
+  auto_close_period: Schema.NullOr(Schema.Finite).pipe(
+    field(25, "Months before stale issues are closed."),
+  ),
+  retired_at: OptionalTimestamp.pipe(field(26, "Time the team was retired.")),
+})
+  .annotate({ description: "Linear teams." })
+  .pipe(Iceberg.identifier("id"));
+
+export type Team = Schema.Schema.Type<typeof TeamSchema>;
+
+export const TeamObjectSchema = TeamSchema.mapFields((fields) => Struct.omit(fields, ["version"]));
+
+export const TeamMembershipSchema = Schema.Struct({
+  ...common("Membership"),
+  team_id: Ref.pipe(field(10, "Team.")),
+  user_id: Ref.pipe(field(11, "User.")),
+  owner: Schema.Boolean.pipe(field(12, "Whether the user owns the team.")),
+})
+  .annotate({ description: "Linear team members. Removed members aren't seen." })
+  .pipe(Iceberg.identifier("id"));
+
+export type TeamMembership = Schema.Schema.Type<typeof TeamMembershipSchema>;
+
+export const TeamMembershipObjectSchema = TeamMembershipSchema.mapFields((fields) =>
+  Struct.omit(fields, ["version"]),
+);
+
+export const WorkflowStateSchema = Schema.Struct({
+  ...common("Workflow state"),
+  name: Schema.String.pipe(field(10, "State name.")),
+  type: Schema.String.pipe(
+    field(11, "State type: triage, backlog, unstarted, started, completed, or canceled."),
+  ),
+  color: Schema.String.pipe(field(12, "State color, as hex.")),
+  description: OptionalString.pipe(field(13, "State description.")),
+  position: Schema.Finite.pipe(field(14, "Order within the team.")),
+  team_id: Ref.pipe(field(15, "Team.")),
+})
+  .annotate({ description: "Linear workflow states. Names the IDs in `issues.state_id`." })
+  .pipe(Iceberg.identifier("id"));
+
+export type WorkflowState = Schema.Schema.Type<typeof WorkflowStateSchema>;
+
+export const WorkflowStateObjectSchema = WorkflowStateSchema.mapFields((fields) =>
+  Struct.omit(fields, ["version"]),
+);
+
+export const UserSchema = Schema.Struct({
+  ...common("User"),
+  _deleted: deleted("user"),
+  name: Schema.String.pipe(field(10, "Full name.")),
+  display_name: Schema.String.pipe(field(11, "Display name.")),
+  email: Schema.String.pipe(field(12, "Email address.")),
+  avatar_url: OptionalString.pipe(field(13, "Avatar image URL.")),
+  title: OptionalString.pipe(field(14, "Job title.")),
+  timezone: OptionalString.pipe(field(15, "Timezone.")),
+  active: Schema.Boolean.pipe(field(16, "Whether the user is active.")),
+  admin: Schema.Boolean.pipe(field(17, "Whether the user is an admin.")),
+  owner: Schema.Boolean.pipe(field(18, "Whether the user owns the workspace.")),
+  guest: Schema.Boolean.pipe(field(19, "Whether the user is a guest.")),
+  app: Schema.Boolean.pipe(field(20, "Whether the user is an app or agent.")),
+  last_seen: OptionalTimestamp.pipe(field(21, "Time the user was last online.")),
+  url: Schema.String.pipe(field(22, "Profile URL.")),
+})
+  .annotate({ description: "Linear users." })
+  .pipe(Iceberg.identifier("id"));
+
+export type User = Schema.Schema.Type<typeof UserSchema>;
+
+export const UserObjectSchema = UserSchema.mapFields((fields) =>
+  Struct.omit(fields, ["version", "_deleted"]),
+);
+
+export const ExternalUserSchema = Schema.Struct({
+  ...common("External user"),
+  name: Schema.String.pipe(field(10, "Name.")),
+  display_name: Schema.String.pipe(field(11, "Display name.")),
+  email: OptionalString.pipe(field(12, "Email address.")),
+  avatar_url: OptionalString.pipe(field(13, "Avatar image URL.")),
+  last_seen: OptionalTimestamp.pipe(field(14, "Time the user was last seen.")),
+})
+  .annotate({
+    description: "People from integrations, such as Slack, who create issues and comments.",
+  })
+  .pipe(Iceberg.identifier("id"));
+
+export type ExternalUser = Schema.Schema.Type<typeof ExternalUserSchema>;
+
+export const ExternalUserObjectSchema = ExternalUserSchema.mapFields((fields) =>
+  Struct.omit(fields, ["version"]),
+);
+
+export const CycleSchema = Schema.Struct({
+  ...common("Cycle"),
+  _deleted: deleted("cycle"),
+  number: Schema.Finite.pipe(field(10, "Cycle number within its team.")),
+  name: OptionalString.pipe(field(11, "Cycle name.")),
+  description: OptionalString.pipe(field(12, "Cycle description.")),
+  team_id: Ref.pipe(field(13, "Team.")),
+  starts_at: Timestamp.pipe(field(14, "Time the cycle starts.")),
+  ends_at: Timestamp.pipe(field(15, "Time the cycle ends.")),
+  completed_at: OptionalTimestamp.pipe(field(16, "Time the cycle was completed.")),
+  auto_archived_at: OptionalTimestamp.pipe(field(17, "Time the cycle was archived automatically.")),
+  progress: Schema.Finite.pipe(field(18, "Share of the scope completed, from 0 to 1.")),
+})
+  .annotate({ description: "Linear cycles." })
+  .pipe(Iceberg.identifier("id"));
+
+export type Cycle = Schema.Schema.Type<typeof CycleSchema>;
+
+export const CycleObjectSchema = CycleSchema.mapFields((fields) =>
+  Struct.omit(fields, ["version", "_deleted"]),
+);

package/src/start.ts

@@ -0,0 +1,47 @@
+import { PgClient } from "@effect/sql-pg";
+import {
+  ConnectorApp,
+  Ingestor,
+  RuntimeConfig,
+  StateStore,
+  Telemetry,
+} from "@useairfoil/connector-kit";
+import { Config, Effect, Layer, Logger, Schema } from "effect";
+import { Command } from "effect/cli";
+
+import { LinearConnector } from "./index";
+
+const ConnectorLayer = LinearConnector.layerConfig(LinearConnector.LinearConfigDef.config);
+const TelemetryLayer = Telemetry.layerOtlp();
+const PostgresLayer = PgClient.layerConfig({
+  url: Config.schema(
+    Schema.Redacted(Schema.NonEmptyString),
+    RuntimeConfig.PlatformRuntimeKey.postgresConnectionString,
+  ),
+  maxConnections: Config.succeed(2),
+  connectTimeout: Config.succeed("5 seconds"),
+  applicationName: Config.succeed("airfoil-producer-linear"),
+});
+const StateStoreLayer = StateStore.layerSql().pipe(Layer.provide(PostgresLayer));
+
+export const startCommand = Command.make("start", {}, () =>
+  Effect.gen(function* () {
+    const port = yield* RuntimeConfig.httpPort;
+    const entrypoint = yield* LinearConnector.LinearConnector;
+
+    return yield* ConnectorApp.start(entrypoint, { port }).pipe(
+      Effect.provide(Ingestor.layerWingsConfig(entrypoint)),
+    );
+  }).pipe(
+    Effect.annotateLogs({ component: "linear" }),
+    Effect.provide(
+      Layer.mergeAll(
+        StateStoreLayer,
+        ConnectorLayer,
+        Logger.layer([Logger.consolePretty()]),
+        TelemetryLayer,
+      ),
+    ),
+    Effect.provide(RuntimeConfig.layerHosted()),
+  ),
+).pipe(Command.withDescription("Run the production connector against Wings"));

package/src/tables.ts

@@ -0,0 +1,83 @@
+import type { Schema } from "effect";
+
+import { CommentSchema } from "./schemas/comments";
+import {
+  CustomerNeedSchema,
+  CustomerSchema,
+  CustomerStatusSchema,
+  CustomerTierSchema,
+} from "./schemas/customers";
+import { DocumentSchema } from "./schemas/documents";
+import {
+  InitiativeLabelSchema,
+  InitiativeRelationSchema,
+  InitiativeSchema,
+  InitiativeToProjectSchema,
+  InitiativeUpdateSchema,
+} from "./schemas/initiatives";
+import {
+  AttachmentSchema,
+  IssueHistorySchema,
+  IssueLabelSchema,
+  IssueRelationSchema,
+  IssueSchema,
+} from "./schemas/issues";
+import {
+  ProjectLabelSchema,
+  ProjectMilestoneSchema,
+  ProjectRelationSchema,
+  ProjectSchema,
+  ProjectStatusSchema,
+  ProjectUpdateSchema,
+} from "./schemas/projects";
+import {
+  IssueToReleaseSchema,
+  ReleaseNoteSchema,
+  ReleasePipelineSchema,
+  ReleaseSchema,
+  ReleaseStageSchema,
+} from "./schemas/releases";
+import {
+  CycleSchema,
+  ExternalUserSchema,
+  TeamMembershipSchema,
+  TeamSchema,
+  UserSchema,
+  WorkflowStateSchema,
+} from "./schemas/teams";
+
+export const tableSchemas: Readonly<Record<string, Schema.Top>> = {
+  issues: IssueSchema,
+  issue_history: IssueHistorySchema,
+  comments: CommentSchema,
+  issue_relations: IssueRelationSchema,
+  attachments: AttachmentSchema,
+  issue_labels: IssueLabelSchema,
+  workflow_states: WorkflowStateSchema,
+  teams: TeamSchema,
+  team_memberships: TeamMembershipSchema,
+  users: UserSchema,
+  external_users: ExternalUserSchema,
+  cycles: CycleSchema,
+  projects: ProjectSchema,
+  project_milestones: ProjectMilestoneSchema,
+  project_updates: ProjectUpdateSchema,
+  project_statuses: ProjectStatusSchema,
+  project_labels: ProjectLabelSchema,
+  project_relations: ProjectRelationSchema,
+  initiatives: InitiativeSchema,
+  initiative_updates: InitiativeUpdateSchema,
+  initiative_labels: InitiativeLabelSchema,
+  initiative_relations: InitiativeRelationSchema,
+  initiative_to_projects: InitiativeToProjectSchema,
+  documents: DocumentSchema,
+  customers: CustomerSchema,
+  customer_needs: CustomerNeedSchema,
+  customer_statuses: CustomerStatusSchema,
+  customer_tiers: CustomerTierSchema,
+  releases: ReleaseSchema,
+  release_notes: ReleaseNoteSchema,
+  release_pipelines: ReleasePipelineSchema,
+  release_stages: ReleaseStageSchema,
+  issue_to_releases: IssueToReleaseSchema,
+};

package/src/webhook/route.ts

@@ -0,0 +1,50 @@
+import { type ResourceDefinition, Webhook } from "@useairfoil/connector-kit";
+import { Effect, Result, Schema } from "effect";
+import { HttpServerResponse } from "effect/http";
+
+import { verifySignature } from "./signature";
+
+export const webhookPath = "/webhooks/linear";
+
+const WebhookEventSchema = Schema.Struct({
+  type: Schema.String,
+  action: Schema.String,
+  webhookTimestamp: Schema.Number,
+  data: Schema.Struct({ id: Schema.String }),
+});
+
+export const makeWebhookRoute = (options: {
+  readonly secret: string;
+  /** Resources by the event's `type`, such as `Issue`. */
+  readonly targets: ReadonlyMap<string, ResourceDefinition>;
+  readonly issueHistory: ResourceDefinition;
+}) =>
+  Webhook.route({
+    path: webhookPath,
+    ackMode: "after-enqueue",
+    schema: WebhookEventSchema,
+    handler: ({ request, rawBody, payload, to }) =>
+      Effect.gen(function* () {
+        const verified = yield* verifySignature({
+          rawBody,
+          header: request.headers["linear-signature"],
+          secret: options.secret,
+          timestamp: payload.webhookTimestamp,
+        }).pipe(Effect.result);
+        if (Result.isFailure(verified)) {
+          return HttpServerResponse.jsonUnsafe(
+            { ok: false, error: verified.failure.message },
+            { status: 401 },
+          );
+        }
+
+        // Polling reads creates and updates.
+        const resource = options.targets.get(payload.type);
+        if (payload.action === "remove" || payload.action === "restore") {
+          if (resource !== undefined) yield* to(resource, payload);
+          if (payload.type === "Issue") yield* to(options.issueHistory, payload);
+        }
+
+        return HttpServerResponse.jsonUnsafe({ ok: true });
+      }),
+  });

package/src/webhook/signature.ts

@@ -0,0 +1,28 @@
+import { ConnectorError } from "@useairfoil/connector-kit";
+import { DateTime, Effect } from "effect";
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+// Linear suggests rejecting deliveries more than a minute old, to stop replays.
+const maxAgeMillis = 60_000;
+
+export const verifySignature = (options: {
+  readonly rawBody: Uint8Array;
+  readonly header: string | undefined;
+  readonly secret: string;
+  /** `webhookTimestamp` from the body, in milliseconds. */
+  readonly timestamp: number | undefined;
+}): Effect.Effect<void, ConnectorError> =>
+  Effect.gen(function* () {
+    const expected = createHmac("sha256", options.secret).update(options.rawBody).digest();
+    const provided = Buffer.from(options.header ?? "", "hex");
+    if (provided.length !== expected.length || !timingSafeEqual(provided, expected)) {
+      return yield* new ConnectorError({ message: "Invalid Linear webhook signature" });
+    }
+    const now = yield* DateTime.nowAsDate;
+    if (
+      options.timestamp === undefined ||
+      Math.abs(now.getTime() - options.timestamp) > maxAgeMillis
+    ) {
+      return yield* new ConnectorError({ message: "Linear webhook is too old" });
+    }
+  });