@toon-protocol/core 1.1.1

package/dist/nip34/index.d.ts

@@ -0,0 +1,350 @@
+import { Event } from 'nostr-tools/pure';
+
+/**
+ * NIP-34: Git Stuff
+ * https://github.com/nostr-protocol/nips/blob/master/34.md
+ *
+ * Event kinds for decentralized code collaboration via Nostr.
+ */
+/**
+ * Repository Announcement (kind 30617)
+ * Replaceable event announcing a Git repository's existence.
+ * Contains clone URLs, maintainers, and metadata.
+ */
+declare const REPOSITORY_ANNOUNCEMENT_KIND = 30617;
+/**
+ * Patch (kind 1617)
+ * Direct patch submission for files under 60KB.
+ * Contains git format-patch output and commit metadata.
+ */
+declare const PATCH_KIND = 1617;
+/**
+ * Pull Request (kind 1618)
+ * Larger submissions or branch-based changes.
+ * References remote repository and commit range.
+ */
+declare const PULL_REQUEST_KIND = 1618;
+/**
+ * Pull Request Status Update (kind 1619)
+ * Updates to existing pull requests.
+ */
+declare const PR_STATUS_UPDATE_KIND = 1619;
+/**
+ * Issue (kind 1621)
+ * Bug reports and feature requests in Markdown format.
+ */
+declare const ISSUE_KIND = 1621;
+/**
+ * Status: Open (kind 1630)
+ */
+declare const STATUS_OPEN_KIND = 1630;
+/**
+ * Status: Applied/Merged (kind 1631)
+ */
+declare const STATUS_APPLIED_KIND = 1631;
+/**
+ * Status: Closed (kind 1632)
+ */
+declare const STATUS_CLOSED_KIND = 1632;
+/**
+ * Status: Draft (kind 1633)
+ */
+declare const STATUS_DRAFT_KIND = 1633;
+/**
+ * All NIP-34 event kinds
+ */
+declare const NIP34_EVENT_KINDS: readonly [30617, 1617, 1618, 1619, 1621, 1630, 1631, 1632, 1633];
+/**
+ * Check if an event kind is a NIP-34 event
+ */
+declare function isNIP34Event(kind: number): boolean;
+
+/**
+ * Helper to get tag value by name
+ */
+declare function getTag(event: Event, tagName: string): string | undefined;
+/**
+ * Helper to get all tag values by name
+ */
+declare function getTags(event: Event, tagName: string): string[];
+/**
+ * Repository Announcement Event (Kind 30617)
+ */
+interface RepositoryAnnouncement extends Event {
+    kind: 30617;
+    tags: (['d', string] | ['name', string] | ['description', string] | ['web', string] | ['clone', string] | ['relays', ...string[]] | ['r', string, 'euc'] | ['maintainers', ...string[]])[];
+}
+/**
+ * Patch Event (Kind 1617)
+ */
+interface PatchEvent extends Event {
+    kind: 1617;
+    content: string;
+    tags: (['a', string] | ['r', string] | ['p', string] | ['commit', string] | ['parent-commit', string] | ['commit-pgp-sig', string] | ['committer', string] | ['t', 'root' | 'reply'])[];
+}
+/**
+ * Pull Request Event (Kind 1618)
+ */
+interface PullRequestEvent extends Event {
+    kind: 1618;
+    tags: (['a', string] | ['r', string] | ['p', string] | ['clone', string] | ['c', string] | ['merge-base', string] | ['subject', string] | ['t', 'root' | 'reply'])[];
+}
+/**
+ * Issue Event (Kind 1621)
+ */
+interface IssueEvent extends Event {
+    kind: 1621;
+    content: string;
+    tags: (['a', string] | ['p', string] | ['subject', string] | ['t', string])[];
+}
+/**
+ * Status Event (Kinds 1630-1633)
+ */
+interface StatusEvent extends Event {
+    kind: 1630 | 1631 | 1632 | 1633;
+    tags: (['e', string] | ['p', string])[];
+}
+/**
+ * Union type of all NIP-34 events
+ */
+type NIP34Event = RepositoryAnnouncement | PatchEvent | PullRequestEvent | IssueEvent | StatusEvent;
+/**
+ * Parse repository reference from 'a' tag
+ * Format: "30617:pubkey:repo-id"
+ */
+interface RepositoryReference {
+    kind: 30617;
+    pubkey: string;
+    repoId: string;
+}
+declare function parseRepositoryReference(aTag: string): RepositoryReference;
+/**
+ * Extract commit message from git format-patch content
+ */
+declare function extractCommitMessage(patchContent: string): string;
+
+/**
+ * Forgejo API Client
+ *
+ * Wrapper around Forgejo REST API for repository and issue management.
+ * Uses fetch API for HTTP requests (compatible with gitea-js SDK structure).
+ */
+interface ForgejoConfig {
+    /** Base URL of Forgejo instance (e.g., "http://forgejo:3000") */
+    baseUrl: string;
+    /** API token for authentication */
+    token: string;
+    /** Default owner/organization for repositories */
+    defaultOwner?: string;
+}
+interface CreateRepositoryOptions {
+    name: string;
+    description?: string;
+    private?: boolean;
+    auto_init?: boolean;
+    default_branch?: string;
+}
+interface CreatePullRequestOptions {
+    owner: string;
+    repo: string;
+    title: string;
+    head: string;
+    base: string;
+    body?: string;
+}
+interface CreateIssueOptions {
+    owner: string;
+    repo: string;
+    title: string;
+    body?: string;
+    labels?: number[];
+}
+interface ForgejoRepository {
+    id: number;
+    name: string;
+    full_name: string;
+    description: string;
+    html_url: string;
+    clone_url: string;
+    ssh_url: string;
+}
+interface ForgejoPullRequest {
+    id: number;
+    number: number;
+    title: string;
+    html_url: string;
+    state: 'open' | 'closed';
+}
+interface ForgejoIssue {
+    id: number;
+    number: number;
+    title: string;
+    html_url: string;
+    state: 'open' | 'closed';
+}
+interface CreateOrUpdateFileOptions {
+    owner: string;
+    repo: string;
+    filepath: string;
+    content: string;
+    message: string;
+    branch?: string;
+    sha?: string;
+}
+interface ForgejoFileResponse {
+    content: {
+        name: string;
+        path: string;
+        sha: string;
+    };
+    commit: {
+        sha: string;
+    };
+}
+/**
+ * Forgejo API Client
+ */
+declare class ForgejoClient {
+    private baseUrl;
+    private token;
+    private defaultOwner?;
+    constructor(config: ForgejoConfig);
+    /**
+     * Make an authenticated API request
+     */
+    private request;
+    /**
+     * Create a new repository
+     */
+    createRepository(options: CreateRepositoryOptions): Promise<ForgejoRepository>;
+    /**
+     * Create a pull request
+     */
+    createPullRequest(options: CreatePullRequestOptions): Promise<ForgejoPullRequest>;
+    /**
+     * Create an issue
+     */
+    createIssue(options: CreateIssueOptions): Promise<ForgejoIssue>;
+    /**
+     * Get repository information
+     */
+    getRepository(owner: string, repo: string): Promise<ForgejoRepository>;
+    /**
+     * Check if repository exists
+     */
+    repositoryExists(owner: string, repo: string): Promise<boolean>;
+    /**
+     * Get clone URL for internal use (within Docker network)
+     */
+    getInternalCloneUrl(owner: string, repo: string): string;
+    /**
+     * Get clone URL for external use
+     */
+    getExternalCloneUrl(repo: ForgejoRepository): string;
+    /**
+     * Create or update a file in a repository
+     */
+    createOrUpdateFile(options: CreateOrUpdateFileOptions): Promise<ForgejoFileResponse>;
+    /**
+     * Create a new branch
+     */
+    createBranch(owner: string, repo: string, branchName: string, fromBranch?: string): Promise<void>;
+    /**
+     * Get file content from repository
+     */
+    getFileContent(owner: string, repo: string, filepath: string, branch?: string): Promise<{
+        content: string;
+        sha: string;
+    } | null>;
+}
+
+/**
+ * NIP-34 Handler
+ *
+ * Processes NIP-34 events (Git stuff on Nostr) and executes corresponding
+ * Git operations on a Forgejo instance.
+ *
+ * Flow:
+ * 1. TOON receives NIP-34 event via ILP payment
+ * 2. BLS validates payment and stores event
+ * 3. BLS calls NIP34Handler.handleEvent()
+ * 4. Handler maps event to Git operation
+ * 5. Operation executes on Forgejo
+ */
+
+interface NIP34Config {
+    /** Forgejo base URL (e.g., "http://forgejo:3000") */
+    forgejoUrl: string;
+    /** Forgejo API token */
+    forgejoToken: string;
+    /** Default owner/org for repositories */
+    defaultOwner: string;
+    /** Git commit identity configuration */
+    gitConfig?: {
+        userName: string;
+        userEmail: string;
+    };
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+interface HandleEventResult {
+    success: boolean;
+    operation: 'repository' | 'patch' | 'pull_request' | 'issue' | 'status' | 'unsupported';
+    message: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * NIP-34 Event Handler
+ *
+ * Maps Nostr events to Git operations on Forgejo.
+ */
+declare class NIP34Handler {
+    private forgejo;
+    private verbose;
+    private defaultOwner;
+    constructor(config: NIP34Config);
+    /**
+     * Handle a NIP-34 event
+     *
+     * This is the main entry point called by the BLS after storing an event.
+     */
+    handleEvent(event: Event): Promise<HandleEventResult>;
+    /**
+     * Handle Repository Announcement (kind 30617)
+     *
+     * Creates a new repository in Forgejo.
+     */
+    private handleRepositoryAnnouncement;
+    /**
+     * Handle Patch (kind 1617)
+     *
+     * Applies a patch to a repository via Forgejo API and creates a pull request.
+     */
+    private handlePatch;
+    /**
+     * Handle Pull Request (kind 1618)
+     *
+     * Creates an issue documenting the pull request (simplified approach without git).
+     */
+    private handlePullRequest;
+    /**
+     * Handle Issue (kind 1621)
+     *
+     * Creates an issue in Forgejo.
+     */
+    private handleIssue;
+    /**
+     * Get operation type from event kind
+     */
+    private getOperationType;
+    /**
+     * Parse git format-patch output to extract file changes
+     */
+    private parsePatch;
+    /**
+     * Log message if verbose mode is enabled
+     */
+    private log;
+}
+
+export { type CreateIssueOptions, type CreateOrUpdateFileOptions, type CreatePullRequestOptions, type CreateRepositoryOptions, ForgejoClient, type ForgejoConfig, type ForgejoFileResponse, type ForgejoIssue, type ForgejoPullRequest, type ForgejoRepository, type HandleEventResult, ISSUE_KIND, type IssueEvent, type NIP34Config, type NIP34Event, NIP34Handler, NIP34_EVENT_KINDS, PATCH_KIND, PR_STATUS_UPDATE_KIND, PULL_REQUEST_KIND, type PatchEvent, type PullRequestEvent, REPOSITORY_ANNOUNCEMENT_KIND, type RepositoryAnnouncement, type RepositoryReference, STATUS_APPLIED_KIND, STATUS_CLOSED_KIND, STATUS_DRAFT_KIND, STATUS_OPEN_KIND, type StatusEvent, extractCommitMessage, getTag, getTags, isNIP34Event, parseRepositoryReference };