@knpkv/atlassian-common 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @knpkv/atlassian-common
+
+## 0.2.0
+
+### Minor Changes
+
+- [#61](https://github.com/knpkv/npm/pull/61) [`fc7be8f`](https://github.com/knpkv/npm/commit/fc7be8ffaf5b6b094c7f81551e8ace6f2a8f2c4c) Thanks @konopkov! - feat: add jira-api-client and atlassian-common packages
+  - New @knpkv/atlassian-common: shared AST types, serializers, auth, and config
+  - New @knpkv/jira-api-client: Effect-based Jira REST API client (openapi-gen)
+  - Updated @knpkv/confluence-api-client: regenerated with openapi-gen
+  - Updated @knpkv/confluence-to-markdown: use new generated API client

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 knpkv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @knpkv/atlassian-common
+
+Shared utilities for Atlassian tools: OAuth2 + PKCE auth, token storage, config paths, AST types, and markdown serialization.
+
+## Installation
+
+```bash
+pnpm add @knpkv/atlassian-common
+```
+
+## Subpath Exports
+
+| Export                                | Contents                                     |
+| ------------------------------------- | -------------------------------------------- |
+| `@knpkv/atlassian-common`             | Everything (AST, auth, config, serializers)  |
+| `@knpkv/atlassian-common/ast`         | Inline, block, macro, and document AST nodes |
+| `@knpkv/atlassian-common/auth`        | OAuth2 endpoints, PKCE, token exchange       |
+| `@knpkv/atlassian-common/config`      | Config paths, schemas, token storage         |
+| `@knpkv/atlassian-common/serializers` | Markdown serializer for AST nodes            |
+
+## OAuth2 + PKCE
+
+Uses Web Crypto API (`globalThis.crypto`) — no `node:crypto` dependency. PKCE code verifier/challenge use `effect/Encoding` for base64url.
+
+```typescript
+import { Effect } from "effect"
+import {
+  generateCodeVerifier,
+  computeCodeChallenge,
+  buildAuthUrl,
+  exchangeCodeForTokens,
+  JIRA_SCOPES
+} from "@knpkv/atlassian-common/auth"
+
+const program = Effect.gen(function* () {
+  // 1. Generate PKCE pair
+  const codeVerifier = generateCodeVerifier()
+  const codeChallenge = yield* computeCodeChallenge(codeVerifier)
+
+  // 2. Build authorization URL
+  const url = buildAuthUrl({
+    clientId: "your-client-id",
+    state: "random-csrf-token",
+    port: 8585,
+    scopes: JIRA_SCOPES,
+    codeChallenge
+  })
+  // → redirect user to `url`
+
+  // 3. Exchange code for tokens (after callback)
+  const tokens = yield* exchangeCodeForTokens({
+    clientId: "your-client-id",
+    clientSecret: "your-client-secret",
+    code: "auth-code-from-callback",
+    redirectUri: "http://localhost:8585/callback",
+    codeVerifier
+  })
+  // tokens.access_token, tokens.refresh_token, tokens.expires_in
+})
+```
+
+## Token Storage
+
+Stores OAuth config and tokens in `~/.config/atlassian/` with 0600 permissions.
+
+```typescript
+import { Effect } from "effect"
+import {
+  saveToken,
+  loadToken,
+  isTokenExpired,
+  saveOAuthConfig,
+  loadOAuthConfig,
+  HomeDirectoryLive
+} from "@knpkv/atlassian-common/config"
+
+const program = Effect.gen(function* () {
+  yield* saveOAuthConfig({ clientId: "...", clientSecret: "..." }, "jira")
+  const config = yield* loadOAuthConfig("jira")
+
+  yield* saveToken({ access_token: "...", refresh_token: "...", expires_in: 3600 }, "jira")
+  const token = yield* loadToken("jira")
+  const expired = isTokenExpired(token)
+}).pipe(Effect.provide(HomeDirectoryLive))
+```
+
+## AST Types
+
+Typed Atlassian Document Format nodes — used by `@knpkv/jira-cli` and `@knpkv/confluence-to-markdown`.
+
+```typescript
+import { Document, Paragraph, Text, Heading, CodeBlock } from "@knpkv/atlassian-common/ast"
+```
+
+## Markdown Serializer
+
+Converts AST nodes to markdown strings.
+
+```typescript
+import { serializeToMarkdown } from "@knpkv/atlassian-common/serializers"
+
+const markdown = serializeToMarkdown(document)
+```
+
+## License
+
+MIT

package/dist/Brand.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Branded string types for type-safe Atlassian domain values.
+ *
+ * **Mental model**
+ *
+ * - **Brand = runtime validation + compile-time narrowing**: Each brand combines
+ *   an Effect `Brand.refined` (throws on invalid values) with an Effect `Schema`
+ *   (composable validation). The `Type` property exposes the branded type for use
+ *   in type annotations.
+ * - **Pattern-guarded strings**: `SpaceKey`, `IssueKey`, `ProjectKey` are regex-branded;
+ *   `PageId` is non-empty branded; `ContentHash` is SHA256 hex branded.
+ *
+ * **Common tasks**
+ *
+ * - Create a custom brand: {@link makeBrandedString}, {@link makeBrandedNonEmptyString}
+ * - Validate a Jira ticket key: {@link IssueKey}
+ * - Validate a content hash: {@link ContentHash}
+ *
+ * **Gotchas**
+ *
+ * - Brand constructors throw synchronously on invalid input — wrap in `Effect.try` if
+ *   the input is untrusted.
+ *
+ * @module
+ */
+import * as Brand from "effect/Brand";
+import * as Schema from "effect/Schema";
+/**
+ * Create a branded string type with pattern validation.
+ *
+ * @example
+ * ```typescript
+ * import { makeBrandedString } from "@knpkv/atlassian-common"
+ *
+ * const IssueKey = makeBrandedString("IssueKey", /^[A-Z]+-\d+$/)
+ * type IssueKey = typeof IssueKey.Type
+ *
+ * const key = IssueKey("PROJ-123") // OK
+ * const bad = IssueKey("invalid")  // Throws
+ * ```
+ *
+ * @category Brand
+ */
+export declare const makeBrandedString: <B extends string>(name: B, pattern: RegExp) => Brand.Brand.Constructor<string & Brand.Brand<B>> & {
+    schema: Schema.brand<Schema.filter<typeof Schema.String>, B>;
+    Type: string & Brand.Brand<B>;
+};
+/**
+ * Create a branded non-empty string type.
+ *
+ * @example
+ * ```typescript
+ * import { makeBrandedNonEmptyString } from "@knpkv/atlassian-common"
+ *
+ * const PageId = makeBrandedNonEmptyString("PageId")
+ * type PageId = typeof PageId.Type
+ *
+ * const id = PageId("12345") // OK
+ * const bad = PageId("")     // Throws
+ * ```
+ *
+ * @category Brand
+ */
+export declare const makeBrandedNonEmptyString: <B extends string>(name: B) => Brand.Brand.Constructor<string & Brand.Brand<B>> & {
+    schema: Schema.brand<Schema.filter<typeof Schema.String>, B>;
+    Type: string & Brand.Brand<B>;
+};
+/**
+ * Confluence Page ID (non-empty string).
+ *
+ * @category Brand
+ */
+export declare const PageId: Brand.Brand.Constructor<string & Brand.Brand<"PageId">> & {
+    schema: Schema.brand<Schema.filter<typeof Schema.String>, "PageId">;
+    Type: string & Brand.Brand<"PageId">;
+};
+export type PageId = typeof PageId.Type;
+/**
+ * Confluence Space Key (uppercase alphanumeric).
+ *
+ * @category Brand
+ */
+export declare const SpaceKey: Brand.Brand.Constructor<string & Brand.Brand<"SpaceKey">> & {
+    schema: Schema.brand<Schema.filter<typeof Schema.String>, "SpaceKey">;
+    Type: string & Brand.Brand<"SpaceKey">;
+};
+export type SpaceKey = typeof SpaceKey.Type;
+/**
+ * Jira Issue Key (PROJECT-123 format).
+ *
+ * @category Brand
+ */
+export declare const IssueKey: Brand.Brand.Constructor<string & Brand.Brand<"IssueKey">> & {
+    schema: Schema.brand<Schema.filter<typeof Schema.String>, "IssueKey">;
+    Type: string & Brand.Brand<"IssueKey">;
+};
+export type IssueKey = typeof IssueKey.Type;
+/**
+ * Jira Project Key (uppercase alphanumeric).
+ *
+ * @category Brand
+ */
+export declare const ProjectKey: Brand.Brand.Constructor<string & Brand.Brand<"ProjectKey">> & {
+    schema: Schema.brand<Schema.filter<typeof Schema.String>, "ProjectKey">;
+    Type: string & Brand.Brand<"ProjectKey">;
+};
+export type ProjectKey = typeof ProjectKey.Type;
+/**
+ * Content hash (SHA256 hex string).
+ *
+ * @category Brand
+ */
+export declare const ContentHash: Brand.Brand.Constructor<string & Brand.Brand<"ContentHash">> & {
+    schema: Schema.brand<Schema.filter<typeof Schema.String>, "ContentHash">;
+    Type: string & Brand.Brand<"ContentHash">;
+};
+export type ContentHash = typeof ContentHash.Type;
+//# sourceMappingURL=Brand.d.ts.map

package/dist/Brand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Brand.d.ts","sourceRoot":"","sources":["../src/Brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,MAAM,EAChD,MAAM,CAAC,EACP,SAAS,MAAM;;;CAkBhB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,SAAS,MAAM,EAAE,MAAM,CAAC;;;CAiBlE,CAAA;AAID;;;;GAIG;AACH,eAAO,MAAM,MAAM;;;CAAsC,CAAA;AACzD,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,QAAQ;;;CAAoD,CAAA;AACzE,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;GAIG;AACH,eAAO,MAAM,QAAQ;;;CAAwD,CAAA;AAC7E,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;CAAsD,CAAA;AAC7E,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,WAAW;;;CAAqD,CAAA;AAC7E,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA"}

package/dist/Brand.js

@@ -0,0 +1,107 @@
+/**
+ * Branded string types for type-safe Atlassian domain values.
+ *
+ * **Mental model**
+ *
+ * - **Brand = runtime validation + compile-time narrowing**: Each brand combines
+ *   an Effect `Brand.refined` (throws on invalid values) with an Effect `Schema`
+ *   (composable validation). The `Type` property exposes the branded type for use
+ *   in type annotations.
+ * - **Pattern-guarded strings**: `SpaceKey`, `IssueKey`, `ProjectKey` are regex-branded;
+ *   `PageId` is non-empty branded; `ContentHash` is SHA256 hex branded.
+ *
+ * **Common tasks**
+ *
+ * - Create a custom brand: {@link makeBrandedString}, {@link makeBrandedNonEmptyString}
+ * - Validate a Jira ticket key: {@link IssueKey}
+ * - Validate a content hash: {@link ContentHash}
+ *
+ * **Gotchas**
+ *
+ * - Brand constructors throw synchronously on invalid input — wrap in `Effect.try` if
+ *   the input is untrusted.
+ *
+ * @module
+ */
+import * as Brand from "effect/Brand";
+import * as Schema from "effect/Schema";
+/**
+ * Create a branded string type with pattern validation.
+ *
+ * @example
+ * ```typescript
+ * import { makeBrandedString } from "@knpkv/atlassian-common"
+ *
+ * const IssueKey = makeBrandedString("IssueKey", /^[A-Z]+-\d+$/)
+ * type IssueKey = typeof IssueKey.Type
+ *
+ * const key = IssueKey("PROJ-123") // OK
+ * const bad = IssueKey("invalid")  // Throws
+ * ```
+ *
+ * @category Brand
+ */
+export const makeBrandedString = (name, pattern) => {
+    const brand = Brand.refined((s) => pattern.test(s), (s) => Brand.error(`Invalid ${name}: ${s} does not match ${pattern}`));
+    const schema = Schema.String.pipe(Schema.pattern(pattern), Schema.brand(name));
+    return Object.assign(brand, {
+        schema,
+        Type: undefined
+    });
+};
+/**
+ * Create a branded non-empty string type.
+ *
+ * @example
+ * ```typescript
+ * import { makeBrandedNonEmptyString } from "@knpkv/atlassian-common"
+ *
+ * const PageId = makeBrandedNonEmptyString("PageId")
+ * type PageId = typeof PageId.Type
+ *
+ * const id = PageId("12345") // OK
+ * const bad = PageId("")     // Throws
+ * ```
+ *
+ * @category Brand
+ */
+export const makeBrandedNonEmptyString = (name) => {
+    const brand = Brand.refined((s) => s.length > 0, (_s) => Brand.error(`${name} cannot be empty`));
+    const schema = Schema.String.pipe(Schema.nonEmptyString(), Schema.brand(name));
+    return Object.assign(brand, {
+        schema,
+        Type: undefined
+    });
+};
+// Common branded types for Atlassian products
+/**
+ * Confluence Page ID (non-empty string).
+ *
+ * @category Brand
+ */
+export const PageId = makeBrandedNonEmptyString("PageId");
+/**
+ * Confluence Space Key (uppercase alphanumeric).
+ *
+ * @category Brand
+ */
+export const SpaceKey = makeBrandedString("SpaceKey", /^[A-Z][A-Z0-9]*$/);
+/**
+ * Jira Issue Key (PROJECT-123 format).
+ *
+ * @category Brand
+ */
+export const IssueKey = makeBrandedString("IssueKey", /^[A-Z][A-Z0-9]*-\d+$/);
+/**
+ * Jira Project Key (uppercase alphanumeric).
+ *
+ * @category Brand
+ */
+export const ProjectKey = makeBrandedString("ProjectKey", /^[A-Z][A-Z0-9]*$/);
+/**
+ * Content hash (SHA256 hex string).
+ *
+ * @category Brand
+ */
+export const ContentHash = makeBrandedString("ContentHash", /^[a-f0-9]{64}$/);
+//# sourceMappingURL=Brand.js.map

package/dist/Brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Brand.js","sourceRoot":"","sources":["../src/Brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,IAAO,EACP,OAAe,EACf,EAAE;IAGF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CACzB,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EACtB,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,mBAAmB,OAAO,EAAE,CAAC,CACtE,CAAA;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAC/B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EACvB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CACnB,CAAA;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE;QAC1B,MAAM;QACN,IAAI,EAAE,SAAmC;KAC1C,CAAC,CAAA;AACJ,CAAC,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAmB,IAAO,EAAE,EAAE;IAGrE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CACzB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,EACnB,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,IAAI,kBAAkB,CAAC,CAC/C,CAAA;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAC/B,MAAM,CAAC,cAAc,EAAE,EACvB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CACnB,CAAA;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE;QAC1B,MAAM;QACN,IAAI,EAAE,SAAmC;KAC1C,CAAC,CAAA;AACJ,CAAC,CAAA;AAED,8CAA8C;AAE9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,yBAAyB,CAAC,QAAQ,CAAC,CAAA;AAGzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAA;AAGzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,UAAU,EAAE,sBAAsB,CAAC,CAAA;AAG7E;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAA;AAG7E;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAA"}

package/dist/Hash.d.ts

@@ -0,0 +1,53 @@
+/**
+ * SHA256 content hashing via Node.js crypto, returning branded {@link ContentHash} values.
+ *
+ * **Mental model**
+ *
+ * - **Effect-wrapped crypto**: {@link hashContent} and {@link hashBuffer} return
+ *   `Effect<ContentHash>` so hashing composes into pipelines without try/catch.
+ * - **Sync escape hatch**: {@link hashContentSync} for contexts where Effect isn't needed.
+ *
+ * **Common tasks**
+ *
+ * - Hash a string: {@link hashContent}
+ * - Hash a buffer: {@link hashBuffer}
+ * - Compare hashes: {@link hashEquals}
+ *
+ * @module
+ */
+import * as Effect from "effect/Effect";
+import { ContentHash } from "./Brand.js";
+/**
+ * Compute SHA256 hash of a string.
+ *
+ * @example
+ * ```typescript
+ * import { hashContent } from "@knpkv/atlassian-common"
+ * import * as Effect from "effect/Effect"
+ *
+ * const hash = Effect.runSync(hashContent("hello world"))
+ * // => "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+ * ```
+ *
+ * @category Hash
+ */
+export declare const hashContent: (content: string) => Effect.Effect<ContentHash>;
+/**
+ * Compute SHA256 hash of a buffer.
+ *
+ * @category Hash
+ */
+export declare const hashBuffer: (buffer: Buffer | Uint8Array) => Effect.Effect<ContentHash>;
+/**
+ * Check if two hashes are equal.
+ *
+ * @category Hash
+ */
+export declare const hashEquals: (a: ContentHash, b: ContentHash) => boolean;
+/**
+ * Synchronous version of hashContent for simple use cases.
+ *
+ * @category Hash
+ */
+export declare const hashContentSync: (content: string) => ContentHash;
+//# sourceMappingURL=Hash.d.ts.map

package/dist/Hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hash.d.ts","sourceRoot":"","sources":["../src/Hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAInE,CAAA;AAEJ;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,GAAG,UAAU,KAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAI9E,CAAA;AAEJ;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,GAAG,WAAW,EAAE,GAAG,WAAW,KAAG,OAAkB,CAAA;AAE9E;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,WAGjD,CAAA"}

package/dist/Hash.js

@@ -0,0 +1,63 @@
+/**
+ * SHA256 content hashing via Node.js crypto, returning branded {@link ContentHash} values.
+ *
+ * **Mental model**
+ *
+ * - **Effect-wrapped crypto**: {@link hashContent} and {@link hashBuffer} return
+ *   `Effect<ContentHash>` so hashing composes into pipelines without try/catch.
+ * - **Sync escape hatch**: {@link hashContentSync} for contexts where Effect isn't needed.
+ *
+ * **Common tasks**
+ *
+ * - Hash a string: {@link hashContent}
+ * - Hash a buffer: {@link hashBuffer}
+ * - Compare hashes: {@link hashEquals}
+ *
+ * @module
+ */
+import * as Effect from "effect/Effect";
+import * as crypto from "node:crypto";
+import { ContentHash } from "./Brand.js";
+/**
+ * Compute SHA256 hash of a string.
+ *
+ * @example
+ * ```typescript
+ * import { hashContent } from "@knpkv/atlassian-common"
+ * import * as Effect from "effect/Effect"
+ *
+ * const hash = Effect.runSync(hashContent("hello world"))
+ * // => "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+ * ```
+ *
+ * @category Hash
+ */
+export const hashContent = (content) => Effect.sync(() => {
+    const hash = crypto.createHash("sha256").update(content, "utf8").digest("hex");
+    return ContentHash(hash);
+});
+/**
+ * Compute SHA256 hash of a buffer.
+ *
+ * @category Hash
+ */
+export const hashBuffer = (buffer) => Effect.sync(() => {
+    const hash = crypto.createHash("sha256").update(buffer).digest("hex");
+    return ContentHash(hash);
+});
+/**
+ * Check if two hashes are equal.
+ *
+ * @category Hash
+ */
+export const hashEquals = (a, b) => a === b;
+/**
+ * Synchronous version of hashContent for simple use cases.
+ *
+ * @category Hash
+ */
+export const hashContentSync = (content) => {
+    const hash = crypto.createHash("sha256").update(content, "utf8").digest("hex");
+    return ContentHash(hash);
+};
+//# sourceMappingURL=Hash.js.map

package/dist/Hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hash.js","sourceRoot":"","sources":["../src/Hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAe,EAA8B,EAAE,CACzE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;IACf,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC9E,OAAO,WAAW,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC,CAAC,CAAA;AAEJ;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAA2B,EAA8B,EAAE,CACpF,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;IACf,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACrE,OAAO,WAAW,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC,CAAC,CAAA;AAEJ;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAc,EAAE,CAAc,EAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAA;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAe,EAAe,EAAE;IAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC9E,OAAO,WAAW,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC,CAAA"}

package/dist/SerializeError.d.ts

@@ -0,0 +1,48 @@
+declare const SerializeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SerializeError";
+} & Readonly<A>;
+/**
+ * Error thrown when serializing AST fails.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect"
+ * import { SerializeError } from "@knpkv/atlassian-common"
+ *
+ * Effect.gen(function* () {
+ *   // ... serialization operation
+ * }).pipe(
+ *   Effect.catchTag("SerializeError", (error) =>
+ *     Effect.sync(() => console.error(`Serialize error: ${error.message}`))
+ *   )
+ * )
+ * ```
+ *
+ * @category Errors
+ */
+export declare class SerializeError extends SerializeError_base<{
+    readonly target: "confluence" | "markdown" | "adf";
+    readonly nodeType: string;
+    readonly message: string;
+}> {
+}
+declare const ParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ParseError";
+} & Readonly<A>;
+/**
+ * Error thrown when parsing content fails.
+ *
+ * @category Errors
+ */
+export declare class ParseError extends ParseError_base<{
+    readonly source: "confluence" | "markdown" | "adf";
+    readonly message: string;
+    readonly position?: {
+        readonly line: number;
+        readonly column: number;
+    };
+    readonly rawContent?: string;
+}> {
+}
+export {};
+//# sourceMappingURL=SerializeError.d.ts.map

package/dist/SerializeError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SerializeError.d.ts","sourceRoot":"","sources":["../src/SerializeError.ts"],"names":[],"mappings":";;;AAcA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAe,SAAQ,oBAAmC;IACrE,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,GAAG,KAAK,CAAA;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAC;CAAG;;;;AAEL;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,GAAG,KAAK,CAAA;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACtE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAC;CAAG"}

package/dist/SerializeError.js

@@ -0,0 +1,42 @@
+/**
+ * Tagged error types for AST serialization and parsing failures.
+ *
+ * **Mental model**
+ *
+ * - **Discriminated by `_tag`**: {@link SerializeError} and {@link ParseError} extend
+ *   `Data.TaggedError`, enabling `Effect.catchTag` for selective recovery.
+ * - **Direction-aware**: Both carry a `target`/`source` field (`"confluence" | "markdown" | "adf"`)
+ *   so handlers know which serialization pipeline failed.
+ *
+ * @module
+ */
+import * as Data from "effect/Data";
+/**
+ * Error thrown when serializing AST fails.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect"
+ * import { SerializeError } from "@knpkv/atlassian-common"
+ *
+ * Effect.gen(function* () {
+ *   // ... serialization operation
+ * }).pipe(
+ *   Effect.catchTag("SerializeError", (error) =>
+ *     Effect.sync(() => console.error(`Serialize error: ${error.message}`))
+ *   )
+ * )
+ * ```
+ *
+ * @category Errors
+ */
+export class SerializeError extends Data.TaggedError("SerializeError") {
+}
+/**
+ * Error thrown when parsing content fails.
+ *
+ * @category Errors
+ */
+export class ParseError extends Data.TaggedError("ParseError") {
+}
+//# sourceMappingURL=SerializeError.js.map

package/dist/SerializeError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SerializeError.js","sourceRoot":"","sources":["../src/SerializeError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AAEnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,cAAe,SAAQ,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAInE;CAAG;AAEL;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,IAAI,CAAC,WAAW,CAAC,YAAY,CAK3D;CAAG"}