@openma/matter-gitlab 0.1.0 → 0.2.0

package/dist/bond/index.d.ts

@@ -1,5 +1,9 @@
-import { BondProvider, ProviderError, SecretRef, TokenGrant } from "@openma/matter/bond";
+import { BondBinding, BondManifest, BondProvider, BondResourceCatalog, ProviderError, SecretRef, TokenGrant } from "@openma/matter/bond";
 import { Effect } from "effect";
+import { JsonValue, WorkEvent } from "@openma/matter";
+import { CredentialResolver } from "@openma/matter/credentials";
+import { IntegrationError, WorkIntegration } from "@openma/matter/integration";
+import { HttpEndpoint } from "@openma/matter/http";
 //#region src/bond/http.d.ts
 type Fetch = typeof globalThis.fetch;
 /**
@@ -300,5 +304,174 @@ interface GitLabBondProviderOptions {
  */
 declare const makeGitLabBondProvider: (options?: GitLabBondProviderOptions) => BondProvider;
 //#endregion
-export { type AuthorizationUrlInput, type CommitIdentity, type Fetch, type GitLabBondProviderOptions, type GitLabInstance, type GitLabOperation, type GitLabRequestClass, type GitLabTokenInfo, type GitLabUser, type OAuthClient, type Pkce, type ProjectRef, type PushPolicy, type ReceivePackCommand, type ReceivePackHead, type ReceivePackHeadParser, type ReceivePackLimits, type ReceivePackParse, type TokenPolicy, type TokenProblem, ZERO_OID, assistedByTrailer, authorizationUrl, canonicalOrigin, classifyGitLabRequest, coAuthoredByTrailer, commitAuthor, createPkce, discoverInstance, evaluatePush, exchangeCode, isValidRefName, makeGitLabBondProvider, makeReceivePackHeadParser, mergeRequestBodyProblem, mergeRequestFooter, mergeRequestPushOptions, parseReceivePackHead, readTokenInfo, readUser, refreshAccessToken, revokeSelfToken, revokeToken, tokenExpiryInstant, validateBotCredential, validatePersonalAccessToken };
+//#region src/bond/resources.d.ts
+/** Minimum GitLab access level per operation: 20 Reporter, 30 Developer. */
+declare const GITLAB_MIN_ACCESS_LEVEL: Readonly<Record<GitLabOperation, number>>;
+declare const gitlabManifest: BondManifest;
+interface GitLabResourceCatalogOptions {
+  readonly fetch?: Fetch;
+}
+/**
+ * Projects as Bond resources, with IDs `project:<numeric id>`. Paths are
+ * display data only. `list` returns projects where the token holds at least
+ * Reporter; `validate` checks the access level each operation needs and
+ * refuses writes to archived projects. An instance administrator without a
+ * membership reports no access level and is treated as having none.
+ */
+declare const makeGitLabResourceCatalog: (options?: GitLabResourceCatalogOptions) => BondResourceCatalog;
+/** The provider, manifest, and resource catalog a host registers for GitLab. */
+declare const makeGitLabBinding: (options?: GitLabBondProviderOptions) => BondBinding;
+//#endregion
+//#region src/bond/integration/client.d.ts
+/**
+ * What a GitLab call needs for one authority: the instance and a token with
+ * API access (a Bond's app principal token, or a test token).
+ */
+interface GitLabCredentials {
+  /** The instance root, for example `https://gitlab.example.com`. */
+  readonly baseUrl: string;
+  readonly token: string;
+}
+type GitLabCredentialResolver = CredentialResolver<GitLabCredentials>;
+type GitLabCredentialSource = (authority: string) => GitLabCredentials | PromiseLike<GitLabCredentials> | Effect.Effect<GitLabCredentials, unknown>;
+type GitLabCredentialOption = GitLabCredentials | GitLabCredentialResolver | GitLabCredentialSource;
+type GitLabCredentialsFor = (authority: string) => Effect.Effect<GitLabCredentials, IntegrationError>;
+declare const makeGitLabCredentialsFor: (option: GitLabCredentialOption) => GitLabCredentialsFor;
+interface GitLabResponse {
+  readonly payload: JsonValue;
+  readonly headers: Headers;
+}
+declare const makeGitLabClient: (input: {
+  readonly credentialsFor: GitLabCredentialsFor;
+  readonly fetch: typeof globalThis.fetch;
+  readonly clock: () => string;
+}) => {
+  request: (options: {
+    readonly authority: string;
+    readonly method: "DELETE" | "GET" | "POST" | "PUT";
+    readonly path: string;
+    readonly body?: Readonly<Record<string, unknown>>;
+  }) => Effect.Effect<GitLabResponse, IntegrationError>;
+};
+type GitLabClient = ReturnType<typeof makeGitLabClient>;
+//#endregion
+//#region src/bond/integration/delivery.d.ts
+/** Every Effect operation `deliver` accepts. */
+declare const GITLAB_OPERATIONS: readonly ["merge_request.note.create", "merge_request.discussion.reply", "issue.note.create", "issue.discussion.reply"];
+type GitLabEffectOperation = (typeof GITLAB_OPERATIONS)[number];
+/**
+ * Delivers GitLab Effects. Every input names the `authority` whose
+ * credentials post the note, the `projectId` (numeric id or full path), the
+ * merge request or issue `iid`, and a non-empty `body`. Discussion replies
+ * also name the `discussionId`; replying to a single comment turns it into a
+ * thread.
+ */
+declare const makeGitLabDelivery: (client: Pick<GitLabClient, "request">) => WorkIntegration["deliver"];
+//#endregion
+//#region src/bond/integration/events.d.ts
+/** Every Event type `ingest` can produce. */
+declare const GITLAB_EVENT_TYPES: readonly string[];
+/**
+ * Turns a verified `GitLabWebhookInput` into one WorkEvent. Inputs of another
+ * kind produce no Events. The Event id combines the authority and the
+ * delivery id, so a GitLab retry is the same Event.
+ */
+declare const normalizeGitLabEvents: (input: unknown, clock: () => string) => Effect.Effect<readonly WorkEvent[], IntegrationError>;
+//#endregion
+//#region src/bond/integration/http.d.ts
+declare const GitLabHttpIngressError_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: "GitLabHttpIngressError";
+} & Readonly<A>;
+declare class GitLabHttpIngressError extends GitLabHttpIngressError_base<{
+  readonly message: string;
+  readonly status: 400 | 401;
+  readonly cause?: unknown;
+}> {}
+declare const GitLabHttpSubmissionError_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: "GitLabHttpSubmissionError";
+} & Readonly<A>;
+declare class GitLabHttpSubmissionError extends GitLabHttpSubmissionError_base<{
+  readonly message: string;
+  readonly status: 503;
+  readonly cause?: unknown;
+}> {}
+/** One verified GitLab webhook delivery, ready for `integration.ingest`. */
+interface GitLabWebhookInput {
+  readonly kind: "gitlab.webhook";
+  /**
+   * Who received the webhook, chosen by the host (for example a Bond id).
+   * It becomes the Event source authority and selects credentials for replies.
+   */
+  readonly authority: string;
+  /** The `X-Gitlab-Event` header, for example `Merge Request Hook`. */
+  readonly eventName: string;
+  /** Stable across GitLab retries; see `decodeGitLabHttpRequest`. */
+  readonly deliveryId: string;
+  /** The `X-Gitlab-Instance` header (GitLab 15.5+), when present. */
+  readonly instance?: string;
+  readonly payload: JsonValue;
+}
+interface GitLabHttpEndpointOptions {
+  /** The secret token configured on the GitLab webhook. */
+  readonly webhookToken: string;
+  readonly authority: string;
+  readonly path?: string;
+  readonly submit: (input: GitLabWebhookInput) => Promise<unknown>;
+}
+/**
+ * Compares the `X-Gitlab-Token` header with the configured secret token in
+ * constant time. Both values are hashed first, so the comparison does not
+ * reveal the secret's length either. An empty configured token never matches.
+ */
+declare const verifyGitLabToken: (input: {
+  readonly webhookToken: string;
+  readonly received: string;
+}) => Effect.Effect<boolean, GitLabHttpIngressError>;
+/**
+ * Verifies and decodes one GitLab webhook request. The delivery id is the
+ * first of `webhook-id` and `Idempotency-Key` (both stable across retries,
+ * GitLab 17.4+) and `X-Gitlab-Event-UUID` (GitLab 14.8+).
+ */
+declare const decodeGitLabHttpRequest: (request: Request, options: Pick<GitLabHttpEndpointOptions, "webhookToken" | "authority">) => Effect.Effect<GitLabWebhookInput, GitLabHttpIngressError>;
+/**
+ * A webhook endpoint for one GitLab authority. Hosts that serve many
+ * authorities from one route call `decodeGitLabHttpRequest` with the token
+ * and authority they look up for the request instead.
+ */
+declare const makeGitLabHttpEndpoint: (options: GitLabHttpEndpointOptions) => HttpEndpoint;
+//#endregion
+//#region src/bond/integration/integration.d.ts
+interface GitLabIntegrationOptions {
+  /**
+   * Credentials for replies: fixed `{ baseUrl, token }`, or a resolver keyed
+   * by the Event authority (for example a Bond's app principal).
+   */
+  readonly credentials: GitLabCredentialOption;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly clock?: () => string;
+}
+/**
+ * The GitLab work integration: `ingest` takes a `GitLabWebhookInput` from
+ * `decodeGitLabHttpRequest`, and `deliver` posts merge request and issue
+ * notes.
+ */
+declare const makeGitLabIntegration: (options: GitLabIntegrationOptions) => WorkIntegration;
+//#endregion
+//#region src/bond/integration/templates.d.ts
+/**
+ * Reviews a merge request when it opens, reopens, or receives new commits,
+ * and posts the review as a note. Title or label edits do not trigger a
+ * review. Draft merge requests are skipped unless `skipDrafts` is false.
+ */
+declare const gitlabMergeRequestReview: import("@openma/matter-loop").Loop;
+/**
+ * Answers a merge request comment that mentions the Agent's GitLab user, in
+ * the same thread. System notes and the Agent's own notes are ignored, so a
+ * reply never triggers another reply.
+ */
+declare const gitlabMention: import("@openma/matter-loop").Loop;
+/** The GitLab templates, in the order a console lists them. */
+declare const gitlabTemplates: readonly [import("@openma/matter-loop").Loop, import("@openma/matter-loop").Loop];
+//#endregion
+export { type AuthorizationUrlInput, type CommitIdentity, type Fetch, GITLAB_EVENT_TYPES, GITLAB_MIN_ACCESS_LEVEL, GITLAB_OPERATIONS, type GitLabBondProviderOptions, type GitLabClient, type GitLabCredentialOption, type GitLabCredentialResolver, type GitLabCredentialSource, type GitLabCredentials, type GitLabEffectOperation, type GitLabHttpEndpointOptions, GitLabHttpIngressError, GitLabHttpSubmissionError, type GitLabInstance, type GitLabIntegrationOptions, type GitLabOperation, type GitLabRequestClass, type GitLabResourceCatalogOptions, type GitLabTokenInfo, type GitLabUser, type GitLabWebhookInput, type OAuthClient, type Pkce, type ProjectRef, type PushPolicy, type ReceivePackCommand, type ReceivePackHead, type ReceivePackHeadParser, type ReceivePackLimits, type ReceivePackParse, type TokenPolicy, type TokenProblem, ZERO_OID, assistedByTrailer, authorizationUrl, canonicalOrigin, classifyGitLabRequest, coAuthoredByTrailer, commitAuthor, createPkce, decodeGitLabHttpRequest, discoverInstance, evaluatePush, exchangeCode, gitlabManifest, gitlabMention, gitlabMergeRequestReview, gitlabTemplates, isValidRefName, makeGitLabBinding, makeGitLabBondProvider, makeGitLabClient, makeGitLabCredentialsFor, makeGitLabDelivery, makeGitLabHttpEndpoint, makeGitLabIntegration, makeGitLabResourceCatalog, makeReceivePackHeadParser, mergeRequestBodyProblem, mergeRequestFooter, mergeRequestPushOptions, normalizeGitLabEvents, parseReceivePackHead, readTokenInfo, readUser, refreshAccessToken, revokeSelfToken, revokeToken, tokenExpiryInstant, validateBotCredential, validatePersonalAccessToken, verifyGitLabToken };
 //# sourceMappingURL=index.d.ts.map