@useairfoil/producer-linear 0.0.1 → 0.0.3

package/src/demo/shared.ts

@@ -0,0 +1,122 @@
+import type { Demo } from "@useairfoil/connector-kit";
+
+import { DateTime, Duration } from "effect";
+
+import type { Comment } from "../schemas/comments";
+import type { CustomerNeed } from "../schemas/customers";
+import type { Attachment, Issue, IssueHistory, IssueRelation } from "../schemas/issues";
+import type { IssueToRelease } from "../schemas/releases";
+
+export const hour = Duration.toMillis(Duration.hours(1));
+export const day = Duration.toMillis(Duration.days(1));
+export const workspace = "https://linear.app/acme";
+
+// Linear IDs are UUIDs. Each kind gets its own first block, and the index ends the ID.
+export const uuid = (kind: number, index: number, part = 0) =>
+  `${kind.toString(16).padStart(8, "0")}-${part.toString(16).padStart(4, "0")}-4000-8000-${index.toString(16).padStart(12, "0")}`;
+
+export const dateOnly = (date: Date) => DateTime.formatIsoDateUtc(DateTime.fromDateUnsafe(date));
+
+export const teams = [
+  { key: "ENG", name: "Engineering", cycles: true, triage: false },
+  { key: "DES", name: "Design", cycles: true, triage: false },
+  { key: "PRD", name: "Product", cycles: false, triage: false },
+  { key: "SUP", name: "Support", cycles: false, triage: true },
+] as const;
+
+export const states = [
+  { name: "Triage", type: "triage", color: "#FC7840" },
+  { name: "Backlog", type: "backlog", color: "#BEC2C8" },
+  { name: "Todo", type: "unstarted", color: "#E2E2E2" },
+  { name: "In Progress", type: "started", color: "#F2C94C" },
+  { name: "In Review", type: "started", color: "#0F783C" },
+  { name: "Done", type: "completed", color: "#5E6AD2" },
+  { name: "Canceled", type: "canceled", color: "#95A2B3" },
+] as const;
+
+export const issueLabels = [
+  { name: "Bug", color: "#EB5757" },
+  { name: "Feature", color: "#BB87FC" },
+  { name: "Improvement", color: "#4EA7FC" },
+  { name: "Docs", color: "#4CB782" },
+] as const;
+
+export const projectStatuses = [
+  { name: "Backlog", type: "backlog", color: "#bec2c8" },
+  { name: "Planned", type: "planned", color: "#e2e2e2" },
+  { name: "In Progress", type: "started", color: "#f2c94c" },
+  { name: "Paused", type: "paused", color: "#95a2b3" },
+  { name: "Completed", type: "completed", color: "#5e6ad2" },
+  { name: "Canceled", type: "canceled", color: "#95a2b3" },
+] as const;
+
+export const projects = [
+  "Onboarding revamp",
+  "Billing v2",
+  "Mobile offline mode",
+  "Search relevance",
+  "SSO for enterprise",
+  "Design system 2.0",
+  "Usage analytics",
+  "API rate limits",
+] as const;
+
+export const priorities = ["No priority", "Urgent", "High", "Medium", "Low"] as const;
+export const userCount = 16;
+export const customerCount = 12;
+export const months = 12;
+export const cycleWeeks = 2;
+export const cyclesBack = 26;
+
+export const teamId = (t: number) => uuid(1, t);
+export const stateId = (t: number, s: number) => uuid(2, t, s);
+export const userId = (u: number) => uuid(3, u);
+export const labelId = (l: number) => uuid(4, l);
+export const projectId = (p: number) => uuid(5, p);
+export const milestoneId = (p: number, m: number) => uuid(6, p, m);
+export const cycleId = (t: number, n: number) => uuid(7, t, n);
+export const customerId = (c: number) => uuid(8, c);
+export const pipelineId = uuid(9, 0);
+export const releaseId = (m: number) => uuid(10, m);
+export const initiativeId = (i: number) => uuid(11, i);
+export const issueId = (index: number) => uuid(12, index);
+
+// Cycles end on the Monday nearest now, so the last one is current.
+export const cycleStart = (now: Date, n: number) =>
+  new Date(now.getTime() - (cyclesBack - n) * cycleWeeks * 7 * day);
+
+export const stamp = (created: Date, updated: Date) => ({
+  version: updated,
+  created_at: created,
+  updated_at: updated,
+  archived_at: null,
+});
+
+export const nameFor = (faker: Demo.DemoContext["faker"]) => {
+  const first = faker.person.firstName();
+  const last = faker.person.lastName();
+
+  return { first, last, name: `${first} ${last}` };
+};
+
+/** Date helpers for one run. `at` keeps a time from going past now. */
+export const clock = ({ faker, now }: Demo.DemoContext) => {
+  const at = (time: number) => new Date(Math.min(time, now.getTime()));
+
+  const later = (from: Date, min: number, max: number) =>
+    at(from.getTime() + faker.number.int({ min, max }));
+
+  return { at, later };
+};
+
+export type Rows = {
+  readonly issues: Array<Issue>;
+  readonly issue_history: Array<IssueHistory>;
+  readonly comments: Array<Comment>;
+  readonly issue_relations: Array<IssueRelation>;
+  readonly attachments: Array<Attachment>;
+  readonly customer_needs: Array<CustomerNeed>;
+  readonly issue_to_releases: Array<IssueToRelease>;
+};
+
+export const verbs = ["Fix", "Add", "Improve", "Update", "Remove", "Support"] as const;

package/src/demo/teams.ts

@@ -0,0 +1,173 @@
+import type { Demo } from "@useairfoil/connector-kit";
+
+import type { IssueLabel } from "../schemas/issues";
+import type {
+  Cycle,
+  ExternalUser,
+  Team,
+  TeamMembership,
+  User,
+  WorkflowState,
+} from "../schemas/teams";
+
+import {
+  cycleId,
+  cyclesBack,
+  cycleStart,
+  cycleWeeks,
+  day,
+  issueLabels,
+  labelId,
+  nameFor,
+  stamp,
+  stateId,
+  states,
+  teamId,
+  teams,
+  userCount,
+  userId,
+  uuid,
+  workspace,
+} from "./shared";
+
+/** Teams with their workflow states, users, labels, and cycles. */
+export const teamTables = ({ faker, now }: Demo.DemoContext, founded: Date) => {
+  const set = stamp(founded, founded);
+
+  const teamRows: Array<Team> = teams.map((team, t) => ({
+    id: teamId(t),
+    ...set,
+    name: team.name,
+    key: team.key,
+    display_name: team.name,
+    description: null,
+    visibility: "public",
+    parent_id: null,
+    timezone: "America/New_York",
+    cycles_enabled: team.cycles,
+    cycle_duration: cycleWeeks,
+    cycle_cooldown_time: 0,
+    cycle_start_day: 1,
+    triage_enabled: team.triage,
+    issue_estimation_type: team.key === "ENG" ? "fibonacci" : "notUsed",
+    default_issue_estimate: team.key === "ENG" ? 1 : 0,
+    auto_archive_period: 6,
+    auto_close_period: 6,
+    retired_at: null,
+  }));
+
+  const stateRows: Array<WorkflowState> = teams.flatMap((team, t) =>
+    states
+      .filter((state) => state.type !== "triage" || team.triage)
+      .map((state, s) => ({
+        id: stateId(t, states.indexOf(state)),
+        ...set,
+        name: state.name,
+        type: state.type,
+        color: state.color,
+        description: null,
+        position: s,
+        team_id: teamId(t),
+      })),
+  );
+
+  const users: Array<User> = Array.from({ length: userCount }, (_, u) => {
+    const person = nameFor(faker);
+    const joined = new Date(founded.getTime() + u * 20 * day);
+
+    return {
+      id: userId(u),
+      ...stamp(joined, joined),
+      _deleted: false,
+      name: person.name,
+      display_name: person.first.toLowerCase(),
+      email: faker.internet
+        .exampleEmail({ firstName: person.first, lastName: person.last })
+        .toLowerCase(),
+      avatar_url: null,
+      title: faker.person.jobTitle(),
+      timezone: faker.helpers.arrayElement(["America/New_York", "Europe/London", "Europe/Berlin"]),
+      active: true,
+      admin: u < 2,
+      owner: u === 0,
+      guest: false,
+      app: false,
+      last_seen: new Date(now.getTime() - faker.number.int({ min: 60_000, max: 3 * day })),
+      url: `${workspace}/profiles/${person.first.toLowerCase()}`,
+    };
+  });
+
+  // Each user is on one team; the first user of each team owns it.
+  const memberships: Array<TeamMembership> = users.map((user, u) => ({
+    id: uuid(13, u),
+    ...stamp(user.created_at, user.created_at),
+    team_id: teamId(u % teams.length),
+    user_id: user.id,
+    owner: u < teams.length,
+  }));
+
+  const externalUsers: Array<ExternalUser> = ["Slack", "Intercom", "Zendesk"].map((source, e) => {
+    const person = nameFor(faker);
+
+    return {
+      id: uuid(14, e),
+      ...set,
+      name: person.name,
+      display_name: `${person.name} (${source})`,
+      email: faker.internet
+        .exampleEmail({ firstName: person.first, lastName: person.last })
+        .toLowerCase(),
+      avatar_url: null,
+      last_seen: new Date(now.getTime() - faker.number.int({ min: day, max: 30 * day })),
+    };
+  });
+
+  const labelRows: Array<IssueLabel> = issueLabels.map((label, l) => ({
+    id: labelId(l),
+    ...set,
+    _deleted: false,
+    name: label.name,
+    description: null,
+    color: label.color,
+    is_group: false,
+    parent_id: null,
+    team_id: null,
+    creator_id: userId(0),
+    retired_at: null,
+  }));
+
+  const cycles: Array<Cycle> = teams.flatMap((team, t) =>
+    team.cycles
+      ? Array.from({ length: cyclesBack + 1 }, (_, n) => {
+          const starts = cycleStart(now, n);
+          const ends = new Date(starts.getTime() + cycleWeeks * 7 * day);
+          const done = ends <= now;
+
+          return {
+            id: cycleId(t, n),
+            ...stamp(starts, done ? ends : now),
+            _deleted: false,
+            number: n + 1,
+            name: null,
+            description: null,
+            team_id: teamId(t),
+            starts_at: starts,
+            ends_at: ends,
+            completed_at: done ? ends : null,
+            auto_archived_at: null,
+            progress: done ? 1 : 0.4,
+          };
+        })
+      : [],
+  );
+
+  return {
+    teams: teamRows,
+    workflow_states: stateRows,
+    users,
+    team_memberships: memberships,
+    external_users: externalUsers,
+    issue_labels: labelRows,
+    cycles,
+  };
+};

package/src/index.ts

@@ -0,0 +1,83 @@
+export * as LinearClient from "./client/client";
+export * as LinearConnector from "./connector";
+export { manifest } from "./manifest";
+export { webhookPath } from "./webhook/route";
+export type { Comment } from "./schemas/comments";
+export { CommentSchema } from "./schemas/comments";
+export type { Customer, CustomerNeed, CustomerStatus, CustomerTier } from "./schemas/customers";
+export {
+  CustomerNeedSchema,
+  CustomerSchema,
+  CustomerStatusSchema,
+  CustomerTierSchema,
+} from "./schemas/customers";
+export type { Document } from "./schemas/documents";
+export { DocumentSchema } from "./schemas/documents";
+export type {
+  Initiative,
+  InitiativeLabel,
+  InitiativeRelation,
+  InitiativeToProject,
+  InitiativeUpdate,
+} from "./schemas/initiatives";
+export {
+  InitiativeLabelSchema,
+  InitiativeRelationSchema,
+  InitiativeSchema,
+  InitiativeToProjectSchema,
+  InitiativeUpdateSchema,
+} from "./schemas/initiatives";
+export type { Attachment, Issue, IssueHistory, IssueLabel, IssueRelation } from "./schemas/issues";
+export {
+  AttachmentSchema,
+  IssueHistorySchema,
+  IssueLabelSchema,
+  IssueRelationSchema,
+  IssueSchema,
+} from "./schemas/issues";
+export type {
+  Project,
+  ProjectLabel,
+  ProjectMilestone,
+  ProjectRelation,
+  ProjectStatus,
+  ProjectUpdate,
+} from "./schemas/projects";
+export {
+  ProjectLabelSchema,
+  ProjectMilestoneSchema,
+  ProjectRelationSchema,
+  ProjectSchema,
+  ProjectStatusSchema,
+  ProjectUpdateSchema,
+} from "./schemas/projects";
+export type {
+  IssueToRelease,
+  Release,
+  ReleaseNote,
+  ReleasePipeline,
+  ReleaseStage,
+} from "./schemas/releases";
+export {
+  IssueToReleaseSchema,
+  ReleaseNoteSchema,
+  ReleasePipelineSchema,
+  ReleaseSchema,
+  ReleaseStageSchema,
+} from "./schemas/releases";
+export type {
+  Cycle,
+  ExternalUser,
+  Team,
+  TeamMembership,
+  User,
+  WorkflowState,
+} from "./schemas/teams";
+export {
+  CycleSchema,
+  ExternalUserSchema,
+  TeamMembershipSchema,
+  TeamSchema,
+  UserSchema,
+  WorkflowStateSchema,
+} from "./schemas/teams";

package/src/main.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import { Command } from "effect/cli";
+import { FetchHttpClient } from "effect/http";
+
+import packageJson from "../package.json";
+import { createTableCommand, setupCommand } from "./create-table";
+import { demoCommand } from "./demo";
+import { sandboxCommand } from "./sandbox";
+import { startCommand } from "./start";
+
+const BootstrapLayer = Layer.mergeAll(FetchHttpClient.layer, NodeServices.layer);
+
+const program = Command.make("producer-linear", {}, () => Effect.void).pipe(
+  Command.withSubcommands([
+    setupCommand,
+    startCommand,
+    sandboxCommand,
+    createTableCommand,
+    demoCommand,
+  ]),
+);
+
+const cli = Command.run(program, { version: packageJson.version });
+
+NodeRuntime.runMain(cli.pipe(Effect.provide(BootstrapLayer), Effect.scoped));

package/src/manifest.ts

@@ -0,0 +1,58 @@
+import * as Manifest from "@useairfoil/connector-kit/manifest";
+
+export const LinearConfigDef = Manifest.defineConfig({
+  apiKey: Manifest.secret({
+    runtimeKey: "LINEAR_API_KEY",
+    description: "Linear personal API key with Read permission, for example lin_api_...",
+  }),
+  webhookSecret: Manifest.secret({
+    runtimeKey: "LINEAR_WEBHOOK_SECRET",
+    description: "Signing secret of the Linear webhook.",
+  }),
+});
+
+export type LinearConfig = Manifest.ConfigValuesOf<typeof LinearConfigDef>;
+
+const capabilities = ["backfill", "changes"] as const;
+const withWebhook = ["backfill", "changes", "webhook"] as const;
+
+export const manifest = Manifest.define({
+  name: "producer-linear",
+  title: "Linear",
+  config: LinearConfigDef.spec,
+  resources: [
+    { name: "issues", capabilities: withWebhook },
+    { name: "issue_history", capabilities: withWebhook },
+    { name: "comments", capabilities: withWebhook },
+    { name: "issue_relations", capabilities },
+    { name: "attachments", capabilities: withWebhook },
+    { name: "issue_labels", capabilities: withWebhook },
+    { name: "workflow_states", capabilities },
+    { name: "teams", capabilities },
+    { name: "team_memberships", capabilities },
+    { name: "users", capabilities: withWebhook },
+    { name: "external_users", capabilities },
+    { name: "cycles", capabilities: withWebhook },
+    { name: "projects", capabilities: withWebhook },
+    { name: "project_milestones", capabilities },
+    { name: "project_updates", capabilities: withWebhook },
+    { name: "project_statuses", capabilities },
+    { name: "project_labels", capabilities: withWebhook },
+    { name: "project_relations", capabilities },
+    { name: "initiatives", capabilities: withWebhook },
+    { name: "initiative_updates", capabilities: withWebhook },
+    { name: "initiative_labels", capabilities },
+    { name: "initiative_relations", capabilities },
+    { name: "initiative_to_projects", capabilities },
+    { name: "documents", capabilities: withWebhook },
+    { name: "customers", capabilities: withWebhook },
+    { name: "customer_needs", capabilities: withWebhook },
+    { name: "customer_statuses", capabilities },
+    { name: "customer_tiers", capabilities },
+    { name: "releases", capabilities },
+    { name: "release_notes", capabilities },
+    { name: "release_pipelines", capabilities },
+    { name: "release_stages", capabilities },
+    { name: "issue_to_releases", capabilities },
+  ],
+});

package/src/resources/comments.ts

@@ -0,0 +1,32 @@
+import { Resource } from "@useairfoil/connector-kit";
+
+import type { LinearClientService } from "../client/client";
+
+import { CommentObjectSchema, CommentSchema } from "../schemas/comments";
+import { backfillList, changesList, checkList, listSpec, rowsOf, webhookList } from "./pages";
+
+export const commentSpec = listSpec({
+  connection: "comments",
+  single: "comment",
+  fields: `id created_at: createdAt updated_at: updatedAt archived_at: archivedAt
+    body user_id: user { id } external_user_id: externalUser { id }
+    issue_id: issueId project_id: projectId project_update_id: projectUpdateId
+    initiative_id: initiativeId initiative_update_id: initiativeUpdateId
+    document_content_id: documentContentId parent_id: parentId quoted_text: quotedText
+    edited_at: editedAt resolved_at: resolvedAt resolving_user_id: resolvingUser { id } url`,
+  item: CommentObjectSchema,
+  updatedAt: (comment) => comment.updated_at,
+  rows: rowsOf((comment) => ({ ...comment, version: comment.updated_at, _deleted: false })),
+});
+
+export const makeComments = (client: LinearClientService) =>
+  Resource.entity({
+    name: "comments",
+    rowSchema: CommentSchema,
+    version: "version",
+
+    check: checkList(client, commentSpec),
+    backfill: backfillList(client, commentSpec),
+    changes: changesList(client, commentSpec),
+    webhook: webhookList(client, commentSpec),
+  });

package/src/resources/customers.ts

@@ -0,0 +1,105 @@
+import { Resource } from "@useairfoil/connector-kit";
+
+import type { LinearClientService } from "../client/client";
+
+import {
+  CustomerNeedObjectSchema,
+  CustomerNeedSchema,
+  CustomerObjectSchema,
+  CustomerSchema,
+  CustomerStatusObjectSchema,
+  CustomerStatusSchema,
+  CustomerTierObjectSchema,
+  CustomerTierSchema,
+} from "../schemas/customers";
+import {
+  backfillList,
+  changesList,
+  checkList,
+  listSources,
+  listSpec,
+  rowsOf,
+  webhookList,
+} from "./pages";
+
+const customerSpec = listSpec({
+  connection: "customers",
+  single: "customer",
+  fields: `id created_at: createdAt updated_at: updatedAt archived_at: archivedAt
+    name domains external_ids: externalIds logo_url: logoUrl owner_id: owner { id }
+    status_id: status { id } tier_id: tier { id } revenue size
+    approximate_need_count: approximateNeedCount url`,
+  item: CustomerObjectSchema,
+  updatedAt: (customer) => customer.updated_at,
+  rows: rowsOf((customer) => ({ ...customer, version: customer.updated_at, _deleted: false })),
+});
+
+export const makeCustomers = (client: LinearClientService) =>
+  Resource.entity({
+    name: "customers",
+    rowSchema: CustomerSchema,
+    version: "version",
+
+    check: checkList(client, customerSpec),
+    backfill: backfillList(client, customerSpec),
+    changes: changesList(client, customerSpec),
+    webhook: webhookList(client, customerSpec),
+  });
+
+const customerNeedSpec = listSpec({
+  connection: "customerNeeds",
+  single: "customerNeed",
+  fields: `id created_at: createdAt updated_at: updatedAt archived_at: archivedAt
+    customer_id: customer { id } issue_id: issue { id } project_id: project { id }
+    original_issue_id: originalIssue { id } comment_id: comment { id }
+    attachment_id: attachment { id } creator_id: creator { id } body priority url`,
+  item: CustomerNeedObjectSchema,
+  updatedAt: (need) => need.updated_at,
+  rows: rowsOf((need) => ({ ...need, version: need.updated_at, _deleted: false })),
+});
+
+export const makeCustomerNeeds = (client: LinearClientService) =>
+  Resource.entity({
+    name: "customer_needs",
+    rowSchema: CustomerNeedSchema,
+    version: "version",
+
+    check: checkList(client, customerNeedSpec),
+    backfill: backfillList(client, customerNeedSpec),
+    changes: changesList(client, customerNeedSpec),
+    webhook: webhookList(client, customerNeedSpec),
+  });
+
+const levelFields = `id created_at: createdAt updated_at: updatedAt archived_at: archivedAt name display_name: displayName description color position`;
+
+const customerStatusSpec = listSpec({
+  connection: "customerStatuses",
+  fields: levelFields,
+  item: CustomerStatusObjectSchema,
+  updatedAt: (status) => status.updated_at,
+  rows: rowsOf((status) => ({ ...status, version: status.updated_at })),
+});
+
+export const makeCustomerStatuses = (client: LinearClientService) =>
+  Resource.entity({
+    name: "customer_statuses",
+    rowSchema: CustomerStatusSchema,
+    version: "version",
+    ...listSources(client, customerStatusSpec),
+  });
+
+const customerTierSpec = listSpec({
+  connection: "customerTiers",
+  fields: levelFields,
+  item: CustomerTierObjectSchema,
+  updatedAt: (tier) => tier.updated_at,
+  rows: rowsOf((tier) => ({ ...tier, version: tier.updated_at })),
+});
+
+export const makeCustomerTiers = (client: LinearClientService) =>
+  Resource.entity({
+    name: "customer_tiers",
+    rowSchema: CustomerTierSchema,
+    version: "version",
+    ...listSources(client, customerTierSpec),
+  });

package/src/resources/documents.ts

@@ -0,0 +1,31 @@
+import { Resource } from "@useairfoil/connector-kit";
+
+import type { LinearClientService } from "../client/client";
+
+import { DocumentObjectSchema, DocumentSchema } from "../schemas/documents";
+import { backfillList, changesList, checkList, listSpec, rowsOf, webhookList } from "./pages";
+
+const documentSpec = listSpec({
+  connection: "documents",
+  single: "document",
+  fields: `id created_at: createdAt updated_at: updatedAt archived_at: archivedAt
+    title content url icon color creator_id: creator { id } updated_by_id: updatedBy { id }
+    project_id: project { id } initiative_id: initiative { id } issue_id: issue { id }
+    cycle_id: cycle { id } team_id: team { id } parent_document_id: parentDocument { id }
+    hidden_at: hiddenAt trashed`,
+  item: DocumentObjectSchema,
+  updatedAt: (document) => document.updated_at,
+  rows: rowsOf((document) => ({ ...document, version: document.updated_at, _deleted: false })),
+});
+
+export const makeDocuments = (client: LinearClientService) =>
+  Resource.entity({
+    name: "documents",
+    rowSchema: DocumentSchema,
+    version: "version",
+
+    check: checkList(client, documentSpec),
+    backfill: backfillList(client, documentSpec),
+    changes: changesList(client, documentSpec),
+    webhook: webhookList(client, documentSpec),
+  });