@knpkv/atlassian-common 0.2.0

package/src/ast/InlineNode.ts

@@ -0,0 +1,328 @@
+/**
+ * Inline-level AST nodes for text content (emphasis, links, mentions, etc.).
+ *
+ * **Mental model**
+ *
+ * - **Leaf and recursive nodes**: `Text`, `InlineCode`, `LineBreak` are leaves;
+ *   `Strong`, `Emphasis`, `Highlight` contain nested `InlineNode` children via `Schema.suspend`.
+ * - **Unsupported preservation**: {@link UnsupportedInline} captures raw content that can't be
+ *   mapped, enabling non-destructive roundtrips.
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+
+/**
+ * Optional raw source HTML for exact roundtrip preservation.
+ *
+ * @category InlineNode
+ */
+export const RawSource = Schema.optional(Schema.String)
+
+/**
+ * Plain text content.
+ *
+ * @example
+ * ```typescript
+ * import { Text } from "@knpkv/atlassian-common/ast"
+ *
+ * const text = new Text({ value: "Hello world" })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Text extends Schema.TaggedClass<Text>()("Text", {
+  value: Schema.String
+}) {}
+
+/**
+ * Inline code span.
+ *
+ * @example
+ * ```typescript
+ * import { InlineCode } from "@knpkv/atlassian-common/ast"
+ *
+ * const code = new InlineCode({ value: "const x = 1" })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class InlineCode extends Schema.TaggedClass<InlineCode>()("InlineCode", {
+  value: Schema.String
+}) {}
+
+/**
+ * Line break element.
+ *
+ * @example
+ * ```typescript
+ * import { LineBreak } from "@knpkv/atlassian-common/ast"
+ *
+ * const br = new LineBreak({})
+ * ```
+ *
+ * @category InlineNode
+ */
+export class LineBreak extends Schema.TaggedClass<LineBreak>()("LineBreak", {}) {}
+
+/**
+ * Unsupported inline element - preserves raw content for round-tripping.
+ *
+ * @example
+ * ```typescript
+ * import { UnsupportedInline } from "@knpkv/atlassian-common/ast"
+ *
+ * const unknown = new UnsupportedInline({
+ *   raw: "<custom-tag>content</custom-tag>",
+ *   source: "confluence"
+ * })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class UnsupportedInline extends Schema.TaggedClass<UnsupportedInline>()("UnsupportedInline", {
+  raw: Schema.String,
+  source: Schema.Literal("confluence", "markdown", "adf")
+}) {}
+
+/**
+ * Emoticon/emoji element.
+ *
+ * @example
+ * ```typescript
+ * import { Emoticon } from "@knpkv/atlassian-common/ast"
+ *
+ * const emoji = new Emoticon({
+ *   shortname: ":grinning:",
+ *   emojiId: "1f600",
+ *   fallback: "grinning"
+ * })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Emoticon extends Schema.TaggedClass<Emoticon>()("Emoticon", {
+  shortname: Schema.String,
+  emojiId: Schema.String,
+  fallback: Schema.String,
+  rawSource: RawSource
+}) {}
+
+/**
+ * User mention element.
+ *
+ * @example
+ * ```typescript
+ * import { UserMention } from "@knpkv/atlassian-common/ast"
+ *
+ * const mention = new UserMention({ accountId: "557058:..." })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class UserMention extends Schema.TaggedClass<UserMention>()("UserMention", {
+  accountId: Schema.String,
+  rawSource: RawSource
+}) {}
+
+/**
+ * Date/time element.
+ *
+ * @example
+ * ```typescript
+ * import { DateTime } from "@knpkv/atlassian-common/ast"
+ *
+ * const date = new DateTime({ datetime: "2026-01-01" })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class DateTime extends Schema.TaggedClass<DateTime>()("DateTime", {
+  datetime: Schema.String,
+  rawSource: RawSource
+}) {}
+
+/**
+ * Underlined text.
+ *
+ * @category InlineNode
+ */
+export class Underline extends Schema.TaggedClass<Underline>()("Underline", {
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Subscript text.
+ *
+ * @category InlineNode
+ */
+export class Subscript extends Schema.TaggedClass<Subscript>()("Subscript", {
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Superscript text.
+ *
+ * @category InlineNode
+ */
+export class Superscript extends Schema.TaggedClass<Superscript>()("Superscript", {
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Strikethrough text.
+ *
+ * @category InlineNode
+ */
+export class Strikethrough extends Schema.TaggedClass<Strikethrough>()("Strikethrough", {
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Colored text with CSS color value.
+ *
+ * @category InlineNode
+ */
+export class ColoredText extends Schema.TaggedClass<ColoredText>()("ColoredText", {
+  color: Schema.String,
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Highlighted text with background color.
+ *
+ * @category InlineNode
+ */
+export class Highlight extends Schema.TaggedClass<Highlight>()("Highlight", {
+  backgroundColor: Schema.String,
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+// Forward declaration for recursive types
+const InlineNodeBase = Schema.Union(
+  Text,
+  InlineCode,
+  LineBreak,
+  Emoticon,
+  UserMention,
+  DateTime,
+  UnsupportedInline
+)
+
+/**
+ * Inline node children schema - use this for recursive inline content.
+ *
+ * @category InlineNode
+ */
+export const InlineNodeChildren: Schema.Schema<ReadonlyArray<InlineNode>> = Schema.suspend(
+  () => Schema.Array(InlineNode)
+)
+
+/**
+ * Strong/bold text.
+ *
+ * @example
+ * ```typescript
+ * import { Strong, Text } from "@knpkv/atlassian-common/ast"
+ *
+ * const bold = new Strong({ children: [new Text({ value: "important" })] })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Strong extends Schema.TaggedClass<Strong>()("Strong", {
+  children: Schema.suspend((): Schema.Schema<ReadonlyArray<InlineNode>> => Schema.Array(InlineNode))
+}) {}
+
+/**
+ * Emphasized/italic text.
+ *
+ * @example
+ * ```typescript
+ * import { Emphasis, Text } from "@knpkv/atlassian-common/ast"
+ *
+ * const italic = new Emphasis({ children: [new Text({ value: "emphasized" })] })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Emphasis extends Schema.TaggedClass<Emphasis>()("Emphasis", {
+  children: Schema.suspend((): Schema.Schema<ReadonlyArray<InlineNode>> => Schema.Array(InlineNode))
+}) {}
+
+/**
+ * Hyperlink with optional title.
+ *
+ * @example
+ * ```typescript
+ * import { Link, Text } from "@knpkv/atlassian-common/ast"
+ *
+ * const link = new Link({
+ *   href: "https://example.com",
+ *   title: "Example",
+ *   children: [new Text({ value: "Click here" })]
+ * })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Link extends Schema.TaggedClass<Link>()("Link", {
+  href: Schema.String,
+  title: Schema.optional(Schema.String),
+  children: Schema.suspend((): Schema.Schema<ReadonlyArray<InlineNode>> => Schema.Array(InlineNode)),
+  rawSource: RawSource
+}) {}
+
+/**
+ * Union of all inline node types.
+ *
+ * @category InlineNode
+ */
+export const InlineNode = Schema.Union(
+  Text,
+  Strong,
+  Emphasis,
+  InlineCode,
+  Link,
+  LineBreak,
+  Emoticon,
+  UserMention,
+  DateTime,
+  Underline,
+  Subscript,
+  Superscript,
+  Strikethrough,
+  ColoredText,
+  Highlight,
+  UnsupportedInline
+)
+
+/**
+ * Type for inline nodes.
+ *
+ * @category Types
+ */
+export type InlineNode =
+  | Text
+  | Strong
+  | Emphasis
+  | InlineCode
+  | Link
+  | LineBreak
+  | Emoticon
+  | UserMention
+  | DateTime
+  | Underline
+  | Subscript
+  | Superscript
+  | Strikethrough
+  | ColoredText
+  | Highlight
+  | UnsupportedInline
+
+/**
+ * Schema type helper for InlineNode.
+ *
+ * @category Types
+ */
+export type InlineNodeSchema = typeof InlineNode

package/src/ast/MacroNode.ts

@@ -0,0 +1,172 @@
+/**
+ * Confluence macro AST nodes (panels, expand, TOC, code, status).
+ *
+ * **Mental model**
+ *
+ * - **Macro = structured metadata + block children**: Each macro wraps Confluence-specific
+ *   semantics (panel type, code language, status color) around standard block content.
+ * - **Serialization-friendly**: Macros carry enough metadata for Markdown comment encoding
+ *   and ADF reconstruction.
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+import { RawSource, SchemaVersion, SimpleBlockNode } from "./BlockNode.js"
+
+/**
+ * Supported panel type names.
+ *
+ * @category MacroNode
+ */
+export const PanelTypes = ["info", "warning", "note", "tip", "error", "panel"] as const
+
+/**
+ * Panel type for info/warning/note macros.
+ *
+ * @category MacroNode
+ */
+export const PanelType = Schema.Literal(...PanelTypes)
+
+/**
+ * Type for panel type.
+ *
+ * @category Types
+ */
+export type PanelType = Schema.Schema.Type<typeof PanelType>
+
+/**
+ * Info/Warning/Note panel macro.
+ *
+ * @example
+ * ```typescript
+ * import { InfoPanel, Paragraph, Text } from "@knpkv/atlassian-common/ast"
+ *
+ * const panel = {
+ *   _tag: "InfoPanel" as const,
+ *   panelType: "warning" as const,
+ *   title: "Important",
+ *   children: [new Paragraph({ children: [new Text({ value: "Be careful!" })] })]
+ * }
+ * ```
+ *
+ * @category MacroNode
+ */
+export const InfoPanel = Schema.Struct({
+  _tag: Schema.Literal("InfoPanel"),
+  version: SchemaVersion,
+  panelType: PanelType,
+  title: Schema.optional(Schema.String),
+  children: Schema.Array(SimpleBlockNode),
+  rawSource: RawSource
+})
+
+/**
+ * Type for InfoPanel.
+ *
+ * @category Types
+ */
+export type InfoPanel = Schema.Schema.Type<typeof InfoPanel>
+
+/**
+ * Expand/collapse macro.
+ *
+ * @category MacroNode
+ */
+export const ExpandMacro = Schema.Struct({
+  _tag: Schema.Literal("ExpandMacro"),
+  version: SchemaVersion,
+  title: Schema.optional(Schema.String),
+  children: Schema.Array(SimpleBlockNode),
+  rawSource: RawSource
+})
+
+/**
+ * Type for ExpandMacro.
+ *
+ * @category Types
+ */
+export type ExpandMacro = Schema.Schema.Type<typeof ExpandMacro>
+
+/**
+ * Table of contents macro.
+ *
+ * @category MacroNode
+ */
+export const TocMacro = Schema.Struct({
+  _tag: Schema.Literal("TocMacro"),
+  version: SchemaVersion,
+  minLevel: Schema.optional(Schema.Number),
+  maxLevel: Schema.optional(Schema.Number),
+  rawSource: RawSource
+})
+
+/**
+ * Type for TocMacro.
+ *
+ * @category Types
+ */
+export type TocMacro = Schema.Schema.Type<typeof TocMacro>
+
+/**
+ * Code macro with syntax highlighting.
+ *
+ * @category MacroNode
+ */
+export const CodeMacro = Schema.Struct({
+  _tag: Schema.Literal("CodeMacro"),
+  version: SchemaVersion,
+  language: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+  code: Schema.String,
+  lineNumbers: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  collapse: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  firstLine: Schema.optional(Schema.Number),
+  rawSource: RawSource
+})
+
+/**
+ * Type for CodeMacro.
+ *
+ * @category Types
+ */
+export type CodeMacro = Schema.Schema.Type<typeof CodeMacro>
+
+/**
+ * Status macro (colored label).
+ *
+ * @category MacroNode
+ */
+export const StatusMacro = Schema.Struct({
+  _tag: Schema.Literal("StatusMacro"),
+  version: SchemaVersion,
+  text: Schema.String,
+  color: Schema.Literal("Grey", "Red", "Yellow", "Green", "Blue"),
+  rawSource: RawSource
+})
+
+/**
+ * Type for StatusMacro.
+ *
+ * @category Types
+ */
+export type StatusMacro = Schema.Schema.Type<typeof StatusMacro>
+
+/**
+ * Union of all macro node types.
+ *
+ * @category MacroNode
+ */
+export const MacroNode = Schema.Union(
+  InfoPanel,
+  ExpandMacro,
+  TocMacro,
+  CodeMacro,
+  StatusMacro
+)
+
+/**
+ * Type for macro nodes.
+ *
+ * @category Types
+ */
+export type MacroNode = InfoPanel | ExpandMacro | TocMacro | CodeMacro | StatusMacro

package/src/ast/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Barrel export for Atlassian AST node types and constructors.
+ *
+ * @module
+ */
+
+// Inline nodes
+export {
+  ColoredText,
+  DateTime,
+  Emoticon,
+  Emphasis,
+  Highlight,
+  InlineCode,
+  InlineNode,
+  type InlineNode as InlineNodeType,
+  InlineNodeChildren,
+  LineBreak,
+  Link,
+  RawSource as InlineRawSource,
+  Strikethrough,
+  Strong,
+  Subscript,
+  Superscript,
+  Text,
+  Underline,
+  UnsupportedInline,
+  UserMention
+} from "./InlineNode.js"
+
+// Block nodes
+export {
+  BlockNode,
+  type BlockNode as BlockNodeType,
+  BlockQuote,
+  CodeBlock,
+  Heading,
+  Image,
+  ImageAttachment,
+  type ImageAttachment as ImageAttachmentType,
+  List,
+  ListItem,
+  Paragraph,
+  RawSource,
+  SchemaVersion,
+  SimpleBlockNode,
+  Table,
+  TableCell,
+  TableRow,
+  TaskItem,
+  type TaskItem as TaskItemType,
+  TaskList,
+  type TaskList as TaskListType,
+  TextAlignment,
+  type TextAlignment as TextAlignmentValue,
+  ThematicBreak,
+  UnsupportedBlock
+} from "./BlockNode.js"
+
+// Macro nodes
+export {
+  CodeMacro,
+  type CodeMacro as CodeMacroType,
+  ExpandMacro,
+  type ExpandMacro as ExpandMacroType,
+  InfoPanel,
+  type InfoPanel as InfoPanelType,
+  MacroNode,
+  type MacroNode as MacroNodeType,
+  PanelType,
+  type PanelType as PanelTypeValue,
+  PanelTypes,
+  StatusMacro,
+  type StatusMacro as StatusMacroType,
+  TocMacro,
+  type TocMacro as TocMacroType
+} from "./MacroNode.js"
+
+// Document
+export {
+  Document,
+  type Document as DocumentType,
+  DocumentNode,
+  type DocumentNode as DocumentNodeType,
+  isDocument,
+  makeDocument
+} from "./Document.js"

package/src/auth/OAuthEndpoints.ts

@@ -0,0 +1,142 @@
+/**
+ * Atlassian OAuth2 endpoint URLs, scope constants, authorization URL builder, and PKCE.
+ *
+ * **Mental model**
+ *
+ * - **Constants + builder**: Endpoint URLs are plain strings; {@link buildAuthUrl}
+ *   assembles the full authorization URL with audience, scopes, CSRF state, and PKCE.
+ * - **Scope sets**: {@link CONFLUENCE_SCOPES} and {@link JIRA_SCOPES} define the
+ *   minimum permissions for each product's OAuth flow.
+ * - **PKCE**: {@link generateCodeVerifier} and {@link computeCodeChallenge} implement
+ *   RFC 7636 S256 to protect the authorization code grant from interception.
+ *
+ * @module
+ */
+import * as Effect from "effect/Effect"
+import * as Encoding from "effect/Encoding"
+
+/**
+ * OAuth2 authorization endpoint.
+ *
+ * @category Endpoints
+ */
+export const AUTH_URL = "https://auth.atlassian.com/authorize"
+
+/**
+ * OAuth2 token endpoint.
+ *
+ * @category Endpoints
+ */
+export const TOKEN_URL = "https://auth.atlassian.com/oauth/token"
+
+/**
+ * OAuth2 token revocation endpoint.
+ *
+ * @category Endpoints
+ */
+export const REVOKE_URL = "https://auth.atlassian.com/oauth/revoke"
+
+/**
+ * Accessible resources endpoint (to get cloud IDs).
+ *
+ * @category Endpoints
+ */
+export const RESOURCES_URL = "https://api.atlassian.com/oauth/token/accessible-resources"
+
+/**
+ * User info endpoint.
+ *
+ * @category Endpoints
+ */
+export const ME_URL = "https://api.atlassian.com/me"
+
+/**
+ * Confluence scopes for OAuth2.
+ *
+ * @category Scopes
+ */
+export const CONFLUENCE_SCOPES = [
+  "read:page:confluence",
+  "write:page:confluence",
+  "delete:page:confluence",
+  "read:me",
+  "offline_access"
+]
+
+/**
+ * Jira scopes for OAuth2.
+ *
+ * @category Scopes
+ */
+export const JIRA_SCOPES = [
+  "read:jira-work",
+  "write:jira-work",
+  "read:jira-user",
+  "manage:jira-project",
+  "manage:jira-configuration",
+  "read:me",
+  "offline_access"
+]
+
+/**
+ * Options for building OAuth2 authorization URL.
+ *
+ * @category Types
+ */
+export interface BuildAuthUrlOptions {
+  /** OAuth2 client ID */
+  readonly clientId: string
+  /** State parameter for CSRF protection */
+  readonly state: string
+  /** Local callback server port */
+  readonly port: number
+  /** OAuth2 scopes */
+  readonly scopes: ReadonlyArray<string>
+  /** PKCE code_challenge (S256). Omit to skip PKCE. */
+  readonly codeChallenge?: string | undefined
+}
+
+/**
+ * Build OAuth2 authorization URL.
+ *
+ * @category Utilities
+ */
+export const buildAuthUrl = (options: BuildAuthUrlOptions): string => {
+  const params = new URLSearchParams({
+    audience: "api.atlassian.com",
+    client_id: options.clientId,
+    scope: options.scopes.join(" "),
+    redirect_uri: `http://localhost:${options.port}/callback`,
+    state: options.state,
+    response_type: "code",
+    prompt: "consent"
+  })
+  if (options.codeChallenge) {
+    params.set("code_challenge", options.codeChallenge)
+    params.set("code_challenge_method", "S256")
+  }
+  return `${AUTH_URL}?${params.toString()}`
+}
+
+/**
+ * Generate a cryptographically random PKCE code verifier (RFC 7636).
+ * Uses Web Crypto API (available in Node 18+, Deno, browsers).
+ *
+ * @category PKCE
+ */
+export const generateCodeVerifier = (): string => {
+  const bytes = new Uint8Array(32)
+  globalThis.crypto.getRandomValues(bytes)
+  return Encoding.encodeBase64Url(bytes)
+}
+
+/**
+ * Compute S256 code challenge from a code verifier (RFC 7636).
+ * Uses Web Crypto `subtle.digest` — returns Effect since digest is async.
+ *
+ * @category PKCE
+ */
+export const computeCodeChallenge = (verifier: string): Effect.Effect<string> =>
+  Effect.promise(() => globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))).pipe(
+    Effect.map((hash) => Encoding.encodeBase64Url(new Uint8Array(hash)))
+  )