@useairfoil/producer-linear 0.0.1 → 0.0.3

package/src/client/client.ts

@@ -0,0 +1,200 @@
+import { ConnectorError, Metrics, Telemetry } from "@useairfoil/connector-kit";
+import {
+  Config,
+  Context,
+  Data,
+  Duration,
+  Effect,
+  Layer,
+  Option,
+  Redacted,
+  Schedule,
+  Schema,
+} from "effect";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+
+import { type LinearConfig, manifest } from "../manifest";
+
+const endpoint = "https://api.linear.app/graphql";
+const maxRetries = 5;
+const retryBaseDelay = Duration.seconds(1);
+const requestTimeout = Duration.minutes(2);
+// Keep retrying rate limits; a failed source stays stopped until restart.
+const limitRetry = Schedule.min([Schedule.exponential("1 minute"), Schedule.spaced("10 minutes")]);
+
+type Variables = Readonly<Record<string, unknown>>;
+
+export type LinearClientService = {
+  readonly query: <A>(
+    schema: Schema.Decoder<A>,
+    document: string,
+    variables?: Variables,
+  ) => Effect.Effect<A, ConnectorError>;
+  /** Like `query`, but "Entity not found" gives `None`. */
+  readonly find: <A>(
+    schema: Schema.Decoder<A>,
+    document: string,
+    variables?: Variables,
+  ) => Effect.Effect<Option.Option<A>, ConnectorError>;
+};
+
+export class LinearClient extends Context.Service<LinearClient, LinearClientService>()(
+  "@useairfoil/producer-linear/LinearClient",
+) {}
+
+const ResponseSchema = Schema.Struct({
+  data: Schema.optional(Schema.Unknown),
+  errors: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        message: Schema.String,
+        extensions: Schema.optional(Schema.Struct({ code: Schema.optional(Schema.String) })),
+      }),
+    ),
+  ),
+});
+
+class RateLimited extends Data.TaggedError("RateLimited")<{ readonly message: string }> {}
+
+const isNotFound = (message: string) => message.startsWith("Entity not found");
+
+const operationName = (document: string) => /^\s*query\s+(\w+)/.exec(document)?.[1] ?? "query";
+
+export const make = Effect.fnUntraced(function* (config: Pick<LinearConfig, "apiKey">) {
+  const client = (yield* HttpClient.HttpClient).pipe(
+    HttpClient.mapRequest((request) =>
+      request.pipe(
+        HttpClientRequest.acceptJson,
+        // Personal API keys go in the header as they are, without `Bearer`.
+        HttpClientRequest.setHeader("Authorization", Redacted.value(config.apiKey)),
+      ),
+    ),
+    HttpClient.retryTransient({
+      schedule: Metrics.retrySchedule({
+        connector: manifest.name,
+        baseDelay: retryBaseDelay,
+        times: maxRetries,
+      }),
+    }),
+  );
+
+  const execute = <A>(
+    schema: Schema.Decoder<A>,
+    document: string,
+    variables: Variables = {},
+  ): Effect.Effect<Option.Option<A>, ConnectorError> => {
+    const operation = operationName(document);
+    return Effect.gen(function* () {
+      const response = yield* client
+        .execute(
+          HttpClientRequest.post(endpoint).pipe(
+            HttpClientRequest.bodyJsonUnsafe({ query: document, variables }),
+          ),
+        )
+        .pipe(
+          Effect.tapError((error) => Telemetry.annotateError("api_http", error)),
+          Effect.mapError(
+            (error) =>
+              new ConnectorError({
+                message: `Linear API request failed for ${operation}`,
+                cause: error,
+              }),
+          ),
+        );
+      // GraphQL errors come with 200 or 400, so read the body first.
+      const body = yield* HttpClientResponse.schemaBodyJson(ResponseSchema)(response).pipe(
+        Effect.tapError((error) => Telemetry.annotateError("api_status", error)),
+        Effect.mapError(
+          (error) =>
+            new ConnectorError({
+              message: `Linear API returned ${response.status} for ${operation}`,
+              cause: error,
+            }),
+        ),
+      );
+      const errors = body.errors ?? [];
+      if (errors.some((error) => error.extensions?.code === "RATELIMITED")) {
+        return yield* new RateLimited({ message: `Linear rate limit reached for ${operation}` });
+      }
+      if (response.status === 401) {
+        return yield* new ConnectorError({ message: "Linear rejected the API key" });
+      }
+      if (errors.length > 0 && errors.every((error) => isNotFound(error.message))) {
+        return Option.none();
+      }
+      const [first] = errors;
+      if (first !== undefined || response.status < 200 || response.status >= 300) {
+        const error = new ConnectorError({
+          message: `Linear API returned ${response.status} for ${operation}${first ? `: ${first.message}` : ""}`,
+          cause: errors,
+        });
+        yield* Telemetry.annotateError("api_graphql", error);
+        return yield* error;
+      }
+      return Option.some(
+        yield* Schema.decodeUnknownEffect(schema)(body.data).pipe(
+          Effect.tapError((error) => Telemetry.annotateError("api_decode", error)),
+          Effect.mapError(
+            (error) =>
+              new ConnectorError({
+                message: `Linear API response for ${operation} does not match the schema`,
+                cause: error,
+              }),
+          ),
+        ),
+      );
+    }).pipe(
+      Effect.timeoutOrElse({
+        duration: requestTimeout,
+        orElse: () =>
+          Effect.fail(
+            new ConnectorError({ message: `Linear API request timed out for ${operation}` }),
+          ),
+      }),
+      Effect.retry({
+        schedule: limitRetry.pipe(
+          Schedule.tap(({ duration }) =>
+            Effect.logWarning("Linear rate limit reached, waiting to try again").pipe(
+              Effect.annotateLogs({ operation, waitMillis: Duration.toMillis(duration) }),
+            ),
+          ),
+        ),
+        while: (error) => error._tag === "RateLimited",
+      }),
+      Effect.catchTag("RateLimited", (error) =>
+        Effect.fail(new ConnectorError({ message: error.message })),
+      ),
+      Effect.withSpan(Telemetry.SpanName.apiFetch, {
+        kind: "client",
+        attributes: { [Telemetry.Attr.apiPath]: `graphql:${operation}` },
+      }),
+    );
+  };
+
+  const query = <A>(schema: Schema.Decoder<A>, document: string, variables?: Variables) =>
+    execute(schema, document, variables).pipe(
+      Effect.flatMap(
+        Option.match({
+          onNone: () =>
+            Effect.fail(
+              new ConnectorError({
+                message: `Linear API found nothing for ${operationName(document)}`,
+              }),
+            ),
+          onSome: Effect.succeed,
+        }),
+      ),
+    );
+
+  return LinearClient.of({ query, find: execute });
+});
+
+export const layer = (
+  config: Pick<LinearConfig, "apiKey">,
+): Layer.Layer<LinearClient, never, HttpClient.HttpClient> =>
+  Layer.effect(LinearClient)(make(config));
+
+export const layerConfig = (
+  config: Config.Wrap<LinearConfig>,
+): Layer.Layer<LinearClient, Config.ConfigError, HttpClient.HttpClient> =>
+  Layer.unwrap(Config.unwrap(config).pipe(Effect.map(layer)));

package/src/connector.ts

@@ -0,0 +1,151 @@
+import { Connector, type ResourceDefinition } from "@useairfoil/connector-kit";
+import { Config, Context, Effect, Layer, Redacted } from "effect";
+
+import type { LinearConfig } from "./manifest";
+
+import * as LinearClient from "./client/client";
+import { makeComments } from "./resources/comments";
+import {
+  makeCustomerNeeds,
+  makeCustomerStatuses,
+  makeCustomerTiers,
+  makeCustomers,
+} from "./resources/customers";
+import { makeDocuments } from "./resources/documents";
+import {
+  makeInitiativeLabels,
+  makeInitiativeRelations,
+  makeInitiativeToProjects,
+  makeInitiativeUpdates,
+  makeInitiatives,
+} from "./resources/initiatives";
+import { makeIssueHistory } from "./resources/issue-history";
+import {
+  makeAttachments,
+  makeIssueLabels,
+  makeIssueRelations,
+  makeIssues,
+} from "./resources/issues";
+import {
+  makeProjectLabels,
+  makeProjectMilestones,
+  makeProjectRelations,
+  makeProjectStatuses,
+  makeProjectUpdates,
+  makeProjects,
+} from "./resources/projects";
+import {
+  makeIssueToReleases,
+  makeReleaseNotes,
+  makeReleasePipelines,
+  makeReleaseStages,
+  makeReleases,
+} from "./resources/releases";
+import {
+  makeCycles,
+  makeExternalUsers,
+  makeTeamMemberships,
+  makeTeams,
+  makeUsers,
+  makeWorkflowStates,
+} from "./resources/teams";
+import { makeWebhookRoute } from "./webhook/route";
+export { LinearConfigDef, manifest } from "./manifest";
+export type { LinearConfig } from "./manifest";
+
+export const make = Effect.fnUntraced(function* (config: LinearConfig) {
+  const client = yield* LinearClient.LinearClient;
+
+  const Issues = makeIssues(client);
+  const IssueHistory = makeIssueHistory(client);
+  const Comments = makeComments(client);
+  const Attachments = makeAttachments(client);
+  const IssueLabels = makeIssueLabels(client);
+  const Users = makeUsers(client);
+  const Cycles = makeCycles(client);
+  const Projects = makeProjects(client);
+  const ProjectUpdates = makeProjectUpdates(client);
+  const ProjectLabels = makeProjectLabels(client);
+  const Initiatives = makeInitiatives(client);
+  const InitiativeUpdates = makeInitiativeUpdates(client);
+  const Documents = makeDocuments(client);
+  const Customers = makeCustomers(client);
+  const CustomerNeeds = makeCustomerNeeds(client);
+
+  return Connector.define({
+    name: "producer-linear",
+    title: "Linear",
+    resources: [
+      Issues,
+      IssueHistory,
+      Comments,
+      makeIssueRelations(client),
+      Attachments,
+      IssueLabels,
+      makeWorkflowStates(client),
+      makeTeams(client),
+      makeTeamMemberships(client),
+      Users,
+      makeExternalUsers(client),
+      Cycles,
+      Projects,
+      makeProjectMilestones(client),
+      ProjectUpdates,
+      makeProjectStatuses(client),
+      ProjectLabels,
+      makeProjectRelations(client),
+      Initiatives,
+      InitiativeUpdates,
+      makeInitiativeLabels(client),
+      makeInitiativeRelations(client),
+      makeInitiativeToProjects(client),
+      Documents,
+      Customers,
+      CustomerNeeds,
+      makeCustomerStatuses(client),
+      makeCustomerTiers(client),
+      makeReleases(client),
+      makeReleaseNotes(client),
+      makeReleasePipelines(client),
+      makeReleaseStages(client),
+      makeIssueToReleases(client),
+    ],
+    webhooks: [
+      makeWebhookRoute({
+        secret: Redacted.value(config.webhookSecret),
+        issueHistory: IssueHistory,
+        // Release webhooks need the Business plan.
+        targets: new Map<string, ResourceDefinition>([
+          ["Issue", Issues],
+          ["Comment", Comments],
+          ["Attachment", Attachments],
+          ["IssueLabel", IssueLabels],
+          ["User", Users],
+          ["Cycle", Cycles],
+          ["Project", Projects],
+          ["ProjectUpdate", ProjectUpdates],
+          ["ProjectLabel", ProjectLabels],
+          ["Initiative", Initiatives],
+          ["InitiativeUpdate", InitiativeUpdates],
+          ["Document", Documents],
+          ["Customer", Customers],
+          ["CustomerNeed", CustomerNeeds],
+        ]),
+      }),
+    ],
+  });
+});
+
+export type LinearConnectorRuntime = Effect.Success<ReturnType<typeof make>>;
+
+export class LinearConnector extends Context.Service<LinearConnector, LinearConnectorRuntime>()(
+  "@useairfoil/producer-linear/LinearConnector",
+) {}
+
+export const layer = (config: LinearConfig) =>
+  Layer.effect(LinearConnector)(
+    make(config).pipe(Effect.annotateLogs({ component: "linear" })),
+  ).pipe(Layer.provide(LinearClient.layer(config)));
+
+export const layerConfig = (config: Config.Wrap<LinearConfig>) =>
+  Layer.unwrap(Config.unwrap(config).pipe(Effect.map(layer)));

package/src/create-table.ts

@@ -0,0 +1,10 @@
+import { ConnectorApp, RuntimeConfig } from "@useairfoil/connector-kit";
+import { Command } from "effect/cli";
+
+import { tableSchemas } from "./tables";
+
+export const createTableCommand = ConnectorApp.makeCreateTableCommand(tableSchemas);
+
+export const setupCommand = ConnectorApp.makeSetupCommand(tableSchemas).pipe(
+  Command.provide(RuntimeConfig.layerHosted()),
+);

package/src/demo/index.ts

@@ -0,0 +1,137 @@
+import { ConnectorApp, Demo, RuntimeConfig } from "@useairfoil/connector-kit";
+import { Command } from "effect/cli";
+
+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";
+import { issueRows } from "./issues";
+import { setupRows } from "./setup";
+
+export const demo = Demo.define({
+  name: "producer-linear",
+  setup: {
+    tables: [
+      Demo.table({ name: "teams", rowSchema: TeamSchema, version: "version" }),
+      Demo.table({ name: "workflow_states", rowSchema: WorkflowStateSchema, version: "version" }),
+      Demo.table({ name: "users", rowSchema: UserSchema, version: "version" }),
+      Demo.table({ name: "team_memberships", rowSchema: TeamMembershipSchema, version: "version" }),
+      Demo.table({ name: "external_users", rowSchema: ExternalUserSchema, version: "version" }),
+      Demo.table({ name: "issue_labels", rowSchema: IssueLabelSchema, version: "version" }),
+      Demo.table({ name: "cycles", rowSchema: CycleSchema, version: "version" }),
+      Demo.table({ name: "project_statuses", rowSchema: ProjectStatusSchema, version: "version" }),
+      Demo.table({ name: "project_labels", rowSchema: ProjectLabelSchema, version: "version" }),
+      Demo.table({ name: "projects", rowSchema: ProjectSchema, version: "version" }),
+      Demo.table({
+        name: "project_milestones",
+        rowSchema: ProjectMilestoneSchema,
+        version: "version",
+      }),
+      Demo.table({ name: "project_updates", rowSchema: ProjectUpdateSchema, version: "version" }),
+      Demo.table({
+        name: "project_relations",
+        rowSchema: ProjectRelationSchema,
+        version: "version",
+      }),
+      Demo.table({ name: "documents", rowSchema: DocumentSchema, version: "version" }),
+      Demo.table({ name: "initiatives", rowSchema: InitiativeSchema, version: "version" }),
+      Demo.table({
+        name: "initiative_labels",
+        rowSchema: InitiativeLabelSchema,
+        version: "version",
+      }),
+      Demo.table({
+        name: "initiative_updates",
+        rowSchema: InitiativeUpdateSchema,
+        version: "version",
+      }),
+      Demo.table({
+        name: "initiative_relations",
+        rowSchema: InitiativeRelationSchema,
+        version: "version",
+      }),
+      Demo.table({
+        name: "initiative_to_projects",
+        rowSchema: InitiativeToProjectSchema,
+        version: "version",
+      }),
+      Demo.table({
+        name: "customer_statuses",
+        rowSchema: CustomerStatusSchema,
+        version: "version",
+      }),
+      Demo.table({ name: "customer_tiers", rowSchema: CustomerTierSchema, version: "version" }),
+      Demo.table({ name: "customers", rowSchema: CustomerSchema, version: "version" }),
+      Demo.table({
+        name: "release_pipelines",
+        rowSchema: ReleasePipelineSchema,
+        version: "version",
+      }),
+      Demo.table({ name: "release_stages", rowSchema: ReleaseStageSchema, version: "version" }),
+      Demo.table({ name: "releases", rowSchema: ReleaseSchema, version: "version" }),
+      Demo.table({ name: "release_notes", rowSchema: ReleaseNoteSchema, version: "version" }),
+    ],
+    rows: setupRows,
+  },
+  group: {
+    tables: [
+      Demo.table({ name: "issues", rowSchema: IssueSchema, version: "version" }),
+      Demo.table({ name: "issue_history", rowSchema: IssueHistorySchema, version: "version" }),
+      Demo.table({ name: "comments", rowSchema: CommentSchema, version: "version" }),
+      Demo.table({ name: "issue_relations", rowSchema: IssueRelationSchema, version: "version" }),
+      Demo.table({ name: "attachments", rowSchema: AttachmentSchema, version: "version" }),
+      Demo.table({ name: "customer_needs", rowSchema: CustomerNeedSchema, version: "version" }),
+      Demo.table({
+        name: "issue_to_releases",
+        rowSchema: IssueToReleaseSchema,
+        version: "version",
+      }),
+    ],
+    rows: issueRows,
+  },
+});
+
+export const demoCommand = ConnectorApp.makeDemoCommand(demo).pipe(
+  Command.provide(RuntimeConfig.layerHosted()),
+);

package/src/demo/initiatives.ts

@@ -0,0 +1,116 @@
+import type { Demo } from "@useairfoil/connector-kit";
+
+import type {
+  Initiative,
+  InitiativeLabel,
+  InitiativeRelation,
+  InitiativeToProject,
+  InitiativeUpdate,
+} from "../schemas/initiatives";
+
+import {
+  dateOnly,
+  day,
+  initiativeId,
+  projectId,
+  projects,
+  stamp,
+  userId,
+  uuid,
+  workspace,
+} from "./shared";
+
+/** Initiatives with their labels, updates, relations, and projects. */
+export const initiativeTables = ({ now }: Demo.DemoContext, founded: Date) => {
+  const set = stamp(founded, founded);
+
+  const initiatives = [
+    "Enterprise readiness",
+    "Self-serve growth",
+    "Platform reliability",
+  ] as const;
+
+  const initiativeRows: Array<Initiative> = initiatives.map((name, i) => ({
+    id: initiativeId(i),
+    ...stamp(founded, now),
+    _deleted: false,
+    name,
+    description: `${name} for this year`,
+    content: null,
+    url: `${workspace}/initiative/${name.toLowerCase().replaceAll(" ", "-")}`,
+    icon: null,
+    color: null,
+    status: "Active",
+    health: "onTrack",
+    health_updated_at: new Date(now.getTime() - 7 * day),
+    priority: BigInt(i + 1),
+    owner_id: userId(i),
+    creator_id: userId(0),
+    parent_initiative_id: null,
+    target_date: dateOnly(new Date(now.getTime() + 90 * day)),
+    started_at: founded,
+    completed_at: null,
+    canceled_at: null,
+    label_ids: [uuid(20, i % 2)],
+    visibility: "workspace",
+    trashed: false,
+  }));
+
+  const initiativeLabels: Array<InitiativeLabel> = ["Company goal", "Team goal"].map((name, l) => ({
+    id: uuid(20, l),
+    ...set,
+    name,
+    description: null,
+    color: "#5E6AD2",
+    is_group: false,
+    parent_id: null,
+    creator_id: userId(0),
+    retired_at: null,
+  }));
+
+  const initiativeUpdates: Array<InitiativeUpdate> = initiatives.flatMap((_, i) =>
+    Array.from({ length: 6 }, (_, k) => {
+      const posted = new Date(now.getTime() - (6 - k) * 30 * day);
+
+      return {
+        id: uuid(21, i, k),
+        ...stamp(posted, posted),
+        _deleted: false,
+        initiative_id: initiativeId(i),
+        user_id: userId(i),
+        body: "Monthly check-in: projects are moving and the main risks are covered.",
+        health: "onTrack",
+        url: `${workspace}/initiative/${i}/updates#${k}`,
+        edited_at: null,
+        comment_count: 0n,
+      };
+    }),
+  );
+
+  const initiativeRelations: Array<InitiativeRelation> = [
+    {
+      id: uuid(22, 0),
+      ...set,
+      initiative_id: initiativeId(0),
+      related_initiative_id: initiativeId(2),
+      sort_order: 0,
+      user_id: userId(0),
+    },
+  ];
+
+  const initiativeProjects: Array<InitiativeToProject> = projects.map((_, p) => ({
+    id: uuid(23, p),
+    ...set,
+    initiative_id: initiativeId(p % initiatives.length),
+    project_id: projectId(p),
+    sort_order: String(p),
+  }));
+
+  return {
+    initiatives: initiativeRows,
+    initiative_labels: initiativeLabels,
+    initiative_updates: initiativeUpdates,
+    initiative_relations: initiativeRelations,
+    initiative_to_projects: initiativeProjects,
+  };
+};