@voltro/plugin-atlassian 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,386 @@
+import { Context } from 'effect';
+import { DEFAULT_POLICY } from '@voltro/integration-http';
+import { Effect } from 'effect';
+import { FetchLike } from '@voltro/integration-http';
+import { HttpPolicy } from '@voltro/integration-http';
+import { Option } from 'effect';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { SubjectService } from '@voltro/protocol';
+import { VoltroPlugin } from '@voltro/protocol';
+
+/** Atlassian's fixed 3LO endpoints (identical for every Cloud site). */
+export declare const ATLASSIAN_AUTHORIZE_URL = "https://auth.atlassian.com/authorize";
+
+export declare const ATLASSIAN_TOKEN_URL = "https://auth.atlassian.com/oauth/token";
+
+/** The slice of `@voltro/cache`'s CacheStore the plugin uses — kept
+ *  structural so the app can pass its own store without a type dep dance. */
+export declare interface AtlassianCache {
+    readonly get: (key: string) => Effect.Effect<Option.Option<unknown>, unknown>;
+    readonly set: (key: string, value: unknown, options?: {
+        readonly ttlMs?: number;
+    }) => Effect.Effect<void, unknown>;
+}
+
+/** The cacheable read namespaces — the reference-data GETs the plugin memoises
+ *  (board config, project, field list, status list). Issue/board *content* is
+ *  never cached (it changes too often to serve stale). */
+export declare type AtlassianCacheNamespace = 'boardConfig' | 'project' | 'field' | 'status';
+
+/**
+ * Resolved per-request Atlassian credentials. The app's
+ * `credentialsResolver(subject)` produces these — the plugin never reads
+ * the app's schema. `patApplication` / `patEnvironment` populate the
+ * mandatory `X-PAT-Application` / `X-PAT-Environment` tracking headers.
+ */
+export declare interface AtlassianCredentials {
+    readonly baseUrl: string;
+    readonly token: string;
+    readonly patApplication: string;
+    readonly patEnvironment: string;
+}
+
+export declare type AtlassianError = JiraError | ConfluenceError | AtlassianOAuthError | AtlassianWebhookError;
+
+/**
+ * OAuth 2.0 (3LO) failure — a rejected/expired grant, a malformed token
+ * response, or a missing-refresh-token re-consent signal. `transient` is
+ * `true` only for a 5xx / network blip at the token endpoint. The
+ * `client_secret` and tokens are NEVER included in `message`.
+ */
+export declare class AtlassianOAuthError extends AtlassianOAuthError_base {
+}
+
+declare const AtlassianOAuthError_base: Schema.TaggedErrorClass<AtlassianOAuthError, "AtlassianOAuthError", {
+    readonly _tag: Schema.tag<"AtlassianOAuthError">;
+} & {
+    message: typeof Schema.String;
+    transient: typeof Schema.Boolean;
+    status: Schema.optional<typeof Schema.Number>;
+}>;
+
+export declare const atlassianPlugin: (options: AtlassianPluginOptions) => VoltroPlugin;
+
+export declare interface AtlassianPluginOptions {
+    /** Resolve the caller's Atlassian credentials from their Subject. */
+    readonly credentialsResolver: CredentialsResolver;
+    /** Distinguishes multiple instances (e.g. two Atlassian sites). */
+    readonly name?: string;
+    /** Override the HTTP client (tests / custom transport). Default global fetch. */
+    readonly fetchImpl?: FetchLike;
+    /** Retry/backoff/timeout overrides (merged over defaults). */
+    readonly policy?: Partial<HttpPolicy>;
+    /** Optional response cache (per-namespace TTLs). */
+    readonly cache?: CacheConfig;
+    /** Enable the public avatar proxy. `resolveCredentials` is a SERVICE
+     *  token (the route is public — no per-user PAT). */
+    readonly avatar?: {
+        readonly resolveCredentials: () => Promise<AtlassianCredentials> | AtlassianCredentials;
+        readonly pathPrefix?: string;
+        readonly fetchImpl?: FetchLike;
+    };
+}
+
+/** Inbound-webhook verification failure — a missing/invalid signature or an
+ *  unparseable envelope. Reject the request with a 401/400. */
+export declare class AtlassianWebhookError extends AtlassianWebhookError_base {
+}
+
+declare const AtlassianWebhookError_base: Schema.TaggedErrorClass<AtlassianWebhookError, "AtlassianWebhookError", {
+    readonly _tag: Schema.tag<"AtlassianWebhookError">;
+} & {
+    message: typeof Schema.String;
+    /** `'signature'` → 401 (bad/missing signature); `'payload'` → 400 (bad body). */
+    reason: Schema.Literal<["signature", "payload"]>;
+}>;
+
+export declare interface AuthorizeUrlOptions {
+    /** Scopes to request. `offline_access` is required to receive a refresh
+     *  token. Common: `['read:jira-work', 'write:jira-work', 'offline_access']`. */
+    readonly scopes: ReadonlyArray<string>;
+    /** Opaque anti-CSRF value echoed back on the redirect — the app generates,
+     *  stores, and verifies it. */
+    readonly state: string;
+    /** `prompt=consent` forces the consent screen (needed to (re)issue a refresh
+     *  token). Default omitted. */
+    readonly prompt?: 'consent';
+    /** `audience`. Default `'api.atlassian.com'` (the Atlassian Cloud gateway). */
+    readonly audience?: string;
+}
+
+/**
+ * Build the URL to redirect a user to for consent. Pure string construction —
+ * no IO. The caller stores `state` and verifies it on the callback.
+ */
+export declare const buildAuthorizeUrl: (config: OAuthConfig, options: AuthorizeUrlOptions) => string;
+
+declare type C<A> = Effect.Effect<A, ConfluenceError, SubjectService>;
+
+export declare interface CacheConfig {
+    readonly store: AtlassianCache;
+    /** Per-namespace TTL in ms (e.g. `{ boardConfig: 60_000, project: 30_000 }`).
+     *  Missing namespace → no TTL (store default). Only the four reference-data
+     *  namespaces are cached — see {@link AtlassianCacheNamespace}. */
+    readonly ttlMs?: Partial<Readonly<Record<AtlassianCacheNamespace, number>>>;
+}
+
+/** Confluence failure — same shape/semantics as {@link JiraError}. */
+export declare class ConfluenceError extends ConfluenceError_base {
+}
+
+declare const ConfluenceError_base: Schema.TaggedErrorClass<ConfluenceError, "ConfluenceError", {
+    readonly _tag: Schema.tag<"ConfluenceError">;
+} & {
+    message: typeof Schema.String;
+    transient: typeof Schema.Boolean;
+    status: Schema.optional<typeof Schema.Number>;
+    code: Schema.optional<Schema.Literal<["session_expired"]>>;
+}>;
+
+export declare class ConfluenceService extends ConfluenceService_base {
+}
+
+declare const ConfluenceService_base: Context.TagClass<ConfluenceService, "@voltro/plugin-atlassian/ConfluenceService", ConfluenceServiceShape>;
+
+export declare interface ConfluenceServiceShape {
+    /** GET /rest/api/content/{id}?expand=body.view,version */
+    readonly getContent: (id: string, options?: {
+        readonly expand?: ReadonlyArray<string>;
+    }) => C<unknown>;
+    /** GET /rest/api/content/search?cql=&expand=version,space */
+    readonly searchContent: (cql: string, options?: {
+        readonly limit?: number;
+        readonly expand?: ReadonlyArray<string>;
+    }) => C<ReadonlyArray<unknown>>;
+    /** GET /rest/api/space/{key} */
+    readonly getSpace: (spaceKey: string) => C<unknown>;
+    /** POST /rest/api/content */
+    readonly createContent: (payload: unknown) => C<unknown>;
+    /** PUT /rest/api/content/{id} (version-bumped) */
+    readonly updateContent: (id: string, payload: unknown, options: {
+        readonly version: number;
+    }) => C<unknown>;
+    /** GET /rest/api/content/{id}/child/attachment */
+    readonly getAttachments: (contentId: string) => C<ReadonlyArray<unknown>>;
+    /** POST /rest/api/content — add a comment to a page. `body` is the comment
+     *  text (storage-format markup). Returns the created comment content. */
+    readonly addComment: (pageId: string, body: string) => C<unknown>;
+    /** GET a PAT-gated binary asset on the Confluence host (an embedded internal
+     *  image / attachment download path that the browser can't fetch
+     *  unauthenticated). SSRF-guarded to the configured host — pass a same-host
+     *  absolute URL or a host-relative path. Returns raw bytes + content-type
+     *  (for inlining as a data URL or re-storing via `@voltro/plugin-storage`). */
+    readonly downloadImage: (url: string) => C<{
+        readonly bytes: Uint8Array;
+        readonly contentType: string | null;
+    }>;
+}
+
+/** App-supplied: maps the request's Subject to Atlassian credentials.
+ *  Fail with the matching typed error (e.g. no PAT on file). */
+export declare type CredentialsResolver = (subject: Subject) => Effect.Effect<AtlassianCredentials, JiraError>;
+
+export declare const DEFAULT_AVATAR_PREFIX = "/_voltro/atlassian/avatar";
+
+/** Default `X-PAT-Application` when the app doesn't override it. */
+export declare const DEFAULT_PAT_APPLICATION = "voltro";
+
+export { DEFAULT_POLICY }
+
+/** How close to expiry (ms) a token is considered stale and refreshed early.
+ *  Default 60s of headroom so an in-flight call doesn't race the deadline. */
+export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
+
+/**
+ * Exchange an authorization `code` (from the redirect callback) for a token
+ * set. Fails with {@link AtlassianOAuthError} on a rejected grant / bad code.
+ */
+export declare const exchangeCode: (config: OAuthExchangeConfig, code: string) => Effect.Effect<OAuthTokens, AtlassianOAuthError>;
+
+export { FetchLike }
+
+/** Jira board data (Greenhopper xboard allData shape — kept loose; the
+ *  app maps `raw` in app code). */
+export declare interface GreenhopperBoard {
+    readonly issues: ReadonlyArray<unknown>;
+    readonly columns: ReadonlyArray<unknown>;
+    readonly swimlanes: ReadonlyArray<unknown>;
+    readonly raw: unknown;
+}
+
+export { HttpPolicy }
+
+declare type J<A> = Effect.Effect<A, JiraError, SubjectService>;
+
+/**
+ * Jira failure. `transient` drives retry — `true` for 408/425/429/5xx +
+ * network blips (worth retrying), `false` for 4xx / config errors. A 401
+ * carries `code: 'session_expired'` (the stored PAT is stale) and is
+ * NON-transient — re-auth, don't retry.
+ */
+export declare class JiraError extends JiraError_base {
+}
+
+declare const JiraError_base: Schema.TaggedErrorClass<JiraError, "JiraError", {
+    readonly _tag: Schema.tag<"JiraError">;
+} & {
+    message: typeof Schema.String;
+    transient: typeof Schema.Boolean;
+    status: Schema.optional<typeof Schema.Number>;
+    code: Schema.optional<Schema.Literal<["session_expired"]>>;
+}>;
+
+export declare class JiraService extends JiraService_base {
+}
+
+declare const JiraService_base: Context.TagClass<JiraService, "@voltro/plugin-atlassian/JiraService", JiraServiceShape>;
+
+export declare interface JiraServiceShape {
+    /** POST /rest/api/2/search — JQL, batched 100. Returns all matching
+     *  issues (follows pagination). */
+    readonly searchIssues: (jql: string, options?: SearchIssuesOptions) => J<ReadonlyArray<unknown>>;
+    /** GET /rest/greenhopper/1.0/xboard/work/allData.json?rapidViewId= */
+    readonly getGreenhopperBoard: (boardId: string | number, options?: {
+        readonly quickFilterId?: string | number;
+    }) => J<GreenhopperBoard>;
+    /** GET /rest/greenhopper/1.0/rapidviewconfig/editmodel?rapidViewId= */
+    readonly getBoardConfig: (boardId: string | number) => J<unknown>;
+    /** GET /rest/agile/1.0/board/{id}/sprint?state=active → null if none
+     *  (failures are swallowed to null). */
+    readonly getActiveSprint: (boardId: string | number) => J<SprintRef | null>;
+    /** GET /rest/agile/1.0/sprint/{id}/issue */
+    readonly getSprintIssues: (sprintId: string | number) => J<ReadonlyArray<unknown>>;
+    /** GET /rest/agile/1.0/sprint/{id} */
+    readonly getSprintInfo: (sprintId: string | number) => J<unknown>;
+    /** GET /rest/api/2/issue/{key} */
+    readonly getIssue: (key: string, options?: {
+        readonly expand?: ReadonlyArray<string>;
+        readonly fields?: ReadonlyArray<string>;
+    }) => J<unknown>;
+    /** GET /rest/api/2/issue/{key}?expand=changelog */
+    readonly getIssueChangelog: (key: string) => J<unknown>;
+    /** GET /rest/api/2/issue/{key}/comment */
+    readonly getComments: (key: string) => J<ReadonlyArray<unknown>>;
+    /** POST /rest/api/2/issue/{key}/comment — add a comment. `body` is the comment
+     *  text (wiki markup on Server/DC). Returns the created comment. */
+    readonly addComment: (key: string, body: string) => J<unknown>;
+    /** Issue `issuelinks` resolved to linked issues (read tool for the AI loop). */
+    readonly getLinkedIssues: (key: string) => J<ReadonlyArray<unknown>>;
+    /** GET /rest/api/2/user?key= | /rest/api/2/user/search?username= */
+    readonly getUser: (by: {
+        readonly key?: string;
+        readonly username?: string;
+    }) => J<unknown>;
+    /** GET /rest/api/2/myself */
+    readonly getMyself: () => J<unknown>;
+    /** GET /rest/api/2/issue/{key}/transitions */
+    readonly getIssueTransitions: (key: string) => J<ReadonlyArray<unknown>>;
+    /** POST /rest/api/2/issue/{key}/transitions */
+    readonly transitionIssue: (key: string, transitionId: string, options?: {
+        readonly fields?: Record<string, unknown>;
+    }) => J<void>;
+    /** POST /rest/api/2/issue */
+    readonly createIssue: (payload: unknown) => J<unknown>;
+    /** PUT /rest/api/2/issue/{key} */
+    readonly updateIssue: (key: string, payload: unknown) => J<void>;
+    /** GET /rest/api/2/project/{key} */
+    readonly getProject: (key: string) => J<unknown>;
+    /** GET /rest/api/2/field */
+    readonly getFields: () => J<ReadonlyArray<unknown>>;
+    /** GET /rest/api/2/status */
+    readonly getStatuses: () => J<ReadonlyArray<unknown>>;
+    /** GET /rest/api/2/filter/{id} (or list) */
+    readonly getFilters: () => J<ReadonlyArray<unknown>>;
+    /** Build the `/secure/useravatar?ownerId=…` URL for a user/owner. */
+    readonly getAvatarUrl: (ownerId: string) => J<string>;
+    /** GET /rest/agile/1.0/board/{id} — the board's metadata (name, type, location). */
+    readonly getBoard: (boardId: string | number) => J<unknown>;
+    /** GET /rest/agile/1.0/board/{id}/quickfilter — the board's configured quick filters (`.values`). */
+    readonly getBoardQuickFilters: (boardId: string | number) => J<ReadonlyArray<unknown>>;
+    /** PUT /rest/api/2/issue/{key}/assignee — assign (Jira Server/DC body `{ name }`); pass `null` to unassign. */
+    readonly assignIssue: (key: string, assignee: string | null) => J<void>;
+    /** DELETE /rest/api/2/issue/{key} — remove an issue (optionally its subtasks). */
+    readonly deleteIssue: (key: string, options?: {
+        readonly deleteSubtasks?: boolean;
+    }) => J<void>;
+    /** The configured Jira base URL for the caller's tenant — for building issue/board deep-links. No HTTP call. */
+    readonly getBaseUrl: () => J<string>;
+    /** Resolve a board's SAVED-FILTER JQL: `/board/{id}/configuration` → `filter.id`
+     *  → `/filter/{id}.jql`. Returns `null` when the board has no resolvable filter.
+     *  Use to scope a query to exactly what the board shows (e.g. sprint reports). */
+    readonly getBoardFilterJql: (boardId: string | number) => J<string | null>;
+}
+
+/** OAuth 2.0 client registration + endpoint config. `clientSecret` is a
+ *  secret — sourced from config/env, never logged, never bundled. */
+export declare interface OAuthConfig {
+    readonly clientId: string;
+    readonly clientSecret: string;
+    /** The exact redirect URI registered on the Atlassian app (must match). */
+    readonly redirectUri: string;
+    /** Override the token endpoint (tests / Atlassian gov-cloud). Default
+     *  {@link ATLASSIAN_TOKEN_URL}. */
+    readonly tokenUrl?: string;
+    /** Override the authorize endpoint. Default {@link ATLASSIAN_AUTHORIZE_URL}. */
+    readonly authorizeUrl?: string;
+}
+
+export declare interface OAuthExchangeConfig extends OAuthConfig {
+    readonly fetchImpl: FetchLike;
+    /** Injectable clock for `expiresAt` (tests). Default `Date.now`. */
+    readonly now?: () => number;
+}
+
+/** A resolved OAuth token set. `expiresAt` is an absolute epoch-ms deadline
+ *  (computed from the endpoint's `expires_in`), so a consumer can decide when
+ *  to refresh without re-deriving it. */
+export declare interface OAuthTokens {
+    readonly accessToken: string;
+    /** Absent when Atlassian didn't return one (e.g. `offline_access` scope not
+     *  requested — then the app must re-consent to get a new access token). */
+    readonly refreshToken?: string;
+    /** Absolute epoch-ms the access token expires at. */
+    readonly expiresAt: number;
+    /** Granted scopes (space-delimited on the wire; split here). */
+    readonly scopes: ReadonlyArray<string>;
+    readonly tokenType: string;
+}
+
+/**
+ * Swap a refresh token for a fresh token set (rotating refresh — Atlassian
+ * returns a NEW refresh token each time, so the app must persist the returned
+ * one). Fails with {@link AtlassianOAuthError} on an expired / revoked grant.
+ */
+export declare const refreshTokens: (config: OAuthExchangeConfig, refreshToken: string) => Effect.Effect<OAuthTokens, AtlassianOAuthError>;
+
+export declare interface SearchIssuesOptions {
+    readonly fields?: ReadonlyArray<string>;
+    readonly maxResults?: number;
+    readonly startAt?: number;
+}
+
+export declare interface SprintRef {
+    readonly id: number;
+    readonly name: string;
+}
+
+/**
+ * Read-refresh-persist in one call: given the currently-stored token set,
+ * return a still-valid one — refreshing (and persisting the rotated set via
+ * `persist`) when it's within `skewMs` of expiry. This is the seam the app
+ * calls before every OAuth-authenticated request; it mirrors the PAT
+ * `credentialsResolver`'s "resolve fresh per request" contract.
+ *
+ * Fails with {@link AtlassianOAuthError} when a refresh is needed but the
+ * stored set has no refresh token (the app must re-consent) or the grant is
+ * rejected.
+ */
+export declare const withFreshToken: (config: WithFreshTokenConfig, stored: OAuthTokens, persist: (tokens: OAuthTokens) => Effect.Effect<void, never> | void) => Effect.Effect<OAuthTokens, AtlassianOAuthError>;
+
+export declare interface WithFreshTokenConfig extends OAuthExchangeConfig {
+    /** Refresh when `expiresAt - now < skewMs`. Default {@link DEFAULT_REFRESH_SKEW_MS}. */
+    readonly skewMs?: number;
+}
+
+export { }