bitbucket-datacenter-api-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 el_jijuna
+
+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/dist/index.d.mts

@@ -0,0 +1,455 @@
+/**
+ * Common pagination and filtering parameters accepted by Bitbucket Data Center list endpoints.
+ */
+interface PaginationParams {
+    /**
+     * Maximum number of results to return per page.
+     * Bitbucket default is `25`, maximum is `1000`.
+     */
+    limit?: number;
+    /**
+     * 0-based index of the first result to return.
+     * Use `nextPageStart` from the previous response to paginate forward.
+     */
+    start?: number;
+}
+/**
+ * Wrapper returned by Bitbucket paginated list endpoints.
+ * @internal
+ */
+interface PagedResponse<T> {
+    values: T[];
+    size: number;
+    limit: number;
+    isLastPage: boolean;
+    start: number;
+    nextPageStart?: number;
+}
+
+/**
+ * Represents a Bitbucket Data Center project.
+ */
+interface BitbucketProject {
+    key: string;
+    id: number;
+    name: string;
+    description?: string;
+    public: boolean;
+    type: 'NORMAL' | 'PERSONAL';
+    links: Record<string, unknown>;
+}
+/**
+ * Query parameters accepted by `GET /rest/api/latest/projects`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-project/#api-api-latest-projects-get}
+ */
+interface ProjectsParams extends PaginationParams {
+    /** Filter by project name (case-insensitive prefix match) */
+    name?: string;
+    /**
+     * Filter by the permission the authenticated user has on the project.
+     * e.g. `'PROJECT_READ'`, `'PROJECT_WRITE'`, `'PROJECT_ADMIN'`
+     */
+    permission?: string;
+}
+
+/**
+ * Represents a Bitbucket Data Center repository.
+ */
+interface BitbucketRepository {
+    slug: string;
+    id: number;
+    name: string;
+    description?: string;
+    state: string;
+    statusMessage: string;
+    forkable: boolean;
+    project: BitbucketProject;
+    public: boolean;
+    links: Record<string, unknown>;
+}
+/**
+ * Query parameters accepted by `GET /rest/api/latest/projects/{key}/repos`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-get}
+ */
+interface ReposParams extends PaginationParams {
+    /** Filter by repository slug (case-insensitive prefix match) */
+    slug?: string;
+    /** Filter by repository name (case-insensitive prefix match) */
+    name?: string;
+    /**
+     * Filter by the permission the authenticated user has on the repository.
+     * e.g. `'REPO_READ'`, `'REPO_WRITE'`, `'REPO_ADMIN'`
+     */
+    permission?: string;
+}
+
+/** A git ref (branch or tag) as referenced in a pull request. */
+interface BitbucketRef {
+    id: string;
+    displayId: string;
+    latestCommit: string;
+    type: 'BRANCH' | 'TAG';
+    repository: {
+        slug: string;
+        id: number;
+        name: string;
+        links: Record<string, unknown>;
+    };
+}
+/** A user participating in a pull request (author, reviewer, or participant). */
+interface BitbucketParticipant {
+    user: {
+        name: string;
+        emailAddress: string;
+        id: number;
+        displayName: string;
+        active: boolean;
+        slug: string;
+        type: string;
+    };
+    role: 'AUTHOR' | 'REVIEWER' | 'PARTICIPANT';
+    approved: boolean;
+    status: 'APPROVED' | 'UNAPPROVED' | 'NEEDS_WORK';
+}
+/**
+ * Represents a Bitbucket Data Center pull request.
+ */
+interface BitbucketPullRequest {
+    id: number;
+    version: number;
+    title: string;
+    description?: string;
+    state: 'OPEN' | 'DECLINED' | 'MERGED';
+    open: boolean;
+    closed: boolean;
+    createdDate: number;
+    updatedDate: number;
+    fromRef: BitbucketRef;
+    toRef: BitbucketRef;
+    locked: boolean;
+    author: BitbucketParticipant;
+    reviewers: BitbucketParticipant[];
+    participants: BitbucketParticipant[];
+    links: Record<string, unknown>;
+}
+/**
+ * Query parameters accepted by `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-pull-requests/#api-api-latest-projects-projectkey-repos-repositoryslug-pull-requests-get}
+ */
+interface PullRequestsParams extends PaginationParams {
+    /**
+     * Filter by state. Defaults to `'OPEN'`.
+     * Use `'ALL'` to retrieve pull requests in any state.
+     */
+    state?: 'OPEN' | 'DECLINED' | 'MERGED' | 'ALL';
+    /**
+     * Filter by direction relative to the current user.
+     * - `'INCOMING'` — pull requests targeting a branch the user owns
+     * - `'OUTGOING'` — pull requests from branches the user owns
+     */
+    direction?: 'INCOMING' | 'OUTGOING';
+    /** Filter by target branch ref (e.g., `'refs/heads/main'`) */
+    at?: string;
+    /** Sort order of results */
+    order?: 'NEWEST' | 'OLDEST' | 'MODIFIED' | 'CLOSED_DATE';
+}
+
+/** Author/committer identity on a git commit. */
+interface BitbucketCommitAuthor {
+    name: string;
+    emailAddress: string;
+}
+/**
+ * Represents a git commit in a Bitbucket Data Center repository.
+ */
+interface BitbucketCommit {
+    /** Full commit SHA */
+    id: string;
+    /** Abbreviated commit SHA */
+    displayId: string;
+    author: BitbucketCommitAuthor;
+    /** Unix timestamp (ms) of the author date */
+    authorTimestamp: number;
+    committer: BitbucketCommitAuthor;
+    /** Unix timestamp (ms) of the committer date */
+    committerTimestamp: number;
+    message: string;
+    parents: Array<{
+        id: string;
+        displayId: string;
+    }>;
+}
+/**
+ * Query parameters accepted by `GET /rest/api/latest/projects/{key}/repos/{slug}/commits`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-commits-get}
+ */
+interface CommitsParams extends PaginationParams {
+    /**
+     * The commit ID or ref to list commits reachable from.
+     * Defaults to the repository's default branch.
+     */
+    until?: string;
+    /** Exclude commits reachable from this commit ID or ref */
+    since?: string;
+    /** Filter commits that touch this file path */
+    path?: string;
+    /** How to handle merge commits */
+    merges?: 'include' | 'exclude' | 'only';
+    /** Follow file renames when filtering by `path` */
+    followRenames?: boolean;
+    /** Silently ignore missing commits referenced by `since` or `until` */
+    ignoreMissing?: boolean;
+}
+
+/**
+ * Represents a Bitbucket repository resource with chainable async methods.
+ *
+ * Implements `PromiseLike<BitbucketRepository>` so it can be awaited directly
+ * to fetch repository info, while also exposing sub-resource methods.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get repository info
+ * const repo = await bbClient.project('PROJ').repo('my-repo');
+ *
+ * // Get pull requests
+ * const prs = await bbClient.project('PROJ').repo('my-repo').pullRequests({ state: 'OPEN' });
+ *
+ * // Get commits
+ * const commits = await bbClient.project('PROJ').repo('my-repo').commits({ limit: 10 });
+ * ```
+ */
+declare class RepositoryResource implements PromiseLike<BitbucketRepository> {
+    private readonly request;
+    private readonly basePath;
+    /** @internal */
+    constructor(request: RequestFn, projectKey: string, repoSlug: string);
+    /**
+     * Allows the resource to be awaited directly, resolving with the repository info.
+     * Delegates to {@link RepositoryResource.get}.
+     */
+    then<TResult1 = BitbucketRepository, TResult2 = never>(onfulfilled?: ((value: BitbucketRepository) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the repository details.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}`
+     *
+     * @returns The repository object
+     */
+    get(): Promise<BitbucketRepository>;
+    /**
+     * Fetches pull requests for this repository.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests`
+     *
+     * @param params - Optional filters: `limit`, `start`, `state`, `direction`, `at`, `order`
+     * @returns An array of pull requests
+     */
+    pullRequests(params?: PullRequestsParams): Promise<BitbucketPullRequest[]>;
+    /**
+     * Fetches commits for this repository.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/commits`
+     *
+     * @param params - Optional filters: `limit`, `start`, `until`, `since`, `path`, `merges`, `followRenames`, `ignoreMissing`
+     * @returns An array of commits
+     */
+    commits(params?: CommitsParams): Promise<BitbucketCommit[]>;
+}
+
+/** @internal */
+type RequestFn = <T>(path: string, params?: Record<string, string | number | boolean>) => Promise<T>;
+/**
+ * Represents a Bitbucket project resource with chainable async methods.
+ *
+ * Implements `PromiseLike<BitbucketProject>` so it can be awaited directly
+ * to fetch the project info, while also exposing sub-resource methods.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get project info
+ * const project = await bbClient.project('PROJ');
+ *
+ * // Get repositories with filters
+ * const repos = await bbClient.project('PROJ').repos({ limit: 50, name: 'api' });
+ *
+ * // Navigate into a specific repository
+ * const prs = await bbClient.project('PROJ').repo('my-repo').pullRequests();
+ * ```
+ */
+declare class ProjectResource implements PromiseLike<BitbucketProject> {
+    private readonly request;
+    private readonly key;
+    /** @internal */
+    constructor(request: RequestFn, key: string);
+    /**
+     * Allows the resource to be awaited directly, resolving with the project info.
+     * Delegates to {@link ProjectResource.get}.
+     */
+    then<TResult1 = BitbucketProject, TResult2 = never>(onfulfilled?: ((value: BitbucketProject) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the project details.
+     *
+     * `GET /rest/api/latest/projects/{key}`
+     *
+     * @returns The project object
+     */
+    get(): Promise<BitbucketProject>;
+    /**
+     * Fetches repositories belonging to this project.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos`
+     *
+     * @param params - Optional filters: `limit`, `start`, `slug`, `name`, `permission`
+     * @returns An array of repositories
+     */
+    repos(params?: ReposParams): Promise<BitbucketRepository[]>;
+    /**
+     * Returns a {@link RepositoryResource} for a given repository slug, providing
+     * access to repository-level data and sub-resources (pull requests, commits, etc.).
+     *
+     * The returned resource can be awaited directly to fetch repository info,
+     * or chained to access nested resources.
+     *
+     * @param repoSlug - The repository slug (e.g., `'my-repo'`)
+     * @returns A chainable repository resource
+     *
+     * @example
+     * ```typescript
+     * const repo    = await bbClient.project('PROJ').repo('my-repo');
+     * const prs     = await bbClient.project('PROJ').repo('my-repo').pullRequests({ state: 'OPEN' });
+     * const commits = await bbClient.project('PROJ').repo('my-repo').commits({ limit: 10 });
+     * ```
+     */
+    repo(repoSlug: string): RepositoryResource;
+}
+
+/**
+ * Constructor options for {@link BitbucketClient}.
+ */
+interface BitbucketClientOptions {
+    /** The base URL of the Bitbucket Data Center instance (e.g., `https://bitbucket.example.com`) */
+    apiUrl: string;
+    /** The username to authenticate with */
+    user: string;
+    /** The personal access token or password to authenticate with */
+    token: string;
+}
+/**
+ * Main entry point for the Bitbucket Data Center REST API client.
+ *
+ * @example
+ * ```typescript
+ * const bbClient = new BitbucketClient({
+ *   apiUrl: 'https://bitbucket.example.com',
+ *   user: 'john.doe',
+ *   token: 'my-token',
+ * });
+ *
+ * const projects = await bbClient.projects({ limit: 50 });
+ * const project  = await bbClient.project('PROJ');
+ * const repos    = await bbClient.project('PROJ').repos({ name: 'api' });
+ * const repo     = await bbClient.project('PROJ').repo('my-repo');
+ * const prs      = await bbClient.project('PROJ').repo('my-repo').pullRequests({ state: 'OPEN' });
+ * const commits  = await bbClient.project('PROJ').repo('my-repo').commits({ limit: 10 });
+ * ```
+ */
+declare class BitbucketClient {
+    private readonly security;
+    /**
+     * @param options - Connection and authentication options
+     * @throws {TypeError} If `apiUrl` is not a valid URL
+     */
+    constructor({ apiUrl, user, token }: BitbucketClientOptions);
+    /**
+     * Performs an authenticated GET request to the Bitbucket REST API.
+     *
+     * @param path - API path relative to `/rest/api/latest` (e.g., `'/projects'`)
+     * @param params - Optional query parameters to append to the URL
+     * @throws {Error} If the HTTP response is not OK
+     * @internal
+     */
+    private request;
+    /**
+     * Fetches all projects accessible to the authenticated user.
+     *
+     * `GET /rest/api/latest/projects`
+     *
+     * @param params - Optional filters: `limit`, `start`, `name`, `permission`
+     * @returns An array of projects
+     */
+    projects(params?: ProjectsParams): Promise<BitbucketProject[]>;
+    /**
+     * Returns a {@link ProjectResource} for a given project key, providing access
+     * to project-level data and sub-resources.
+     *
+     * The returned resource can be awaited directly to fetch project info,
+     * or chained to access nested resources.
+     *
+     * @param projectKey - The project key (e.g., `'PROJ'`)
+     * @returns A chainable project resource
+     *
+     * @example
+     * ```typescript
+     * const project = await bbClient.project('PROJ');
+     * const repos   = await bbClient.project('PROJ').repos({ limit: 10 });
+     * const prs     = await bbClient.project('PROJ').repo('my-repo').pullRequests();
+     * ```
+     */
+    project(projectKey: string): ProjectResource;
+}
+
+/**
+ * Handles Basic Authentication for Bitbucket Data Center REST API requests.
+ *
+ * @example
+ * ```typescript
+ * const security = new Security(
+ *   'https://bitbucket.example.com',
+ *   'my-user',
+ *   'my-token'
+ * );
+ *
+ * const headers = security.getHeaders();
+ * // { Authorization: 'Basic <base64>', 'Content-Type': 'application/json', Accept: 'application/json' }
+ * ```
+ */
+declare class Security {
+    private readonly apiUrl;
+    private readonly authorizationHeader;
+    /**
+     * Creates a new Security instance with Basic Authentication credentials.
+     *
+     * @param apiUrl - The base URL of the Bitbucket Data Center instance (e.g., `https://bitbucket.example.com`).
+     *   Must be a valid URL; throws if it cannot be parsed.
+     * @param user - The username to authenticate with
+     * @param token - The personal access token or password to authenticate with
+     *
+     * @throws {TypeError} If `apiUrl` is not a valid URL
+     */
+    constructor(apiUrl: string, user: string, token: string);
+    /**
+     * Returns the base URL of the Bitbucket Data Center instance, without a trailing slash.
+     *
+     * @returns The API base URL
+     */
+    getApiUrl(): string;
+    /**
+     * Returns the value of the `Authorization` header for Basic Authentication.
+     *
+     * @returns The Authorization header value in the format `Basic <base64-encoded-credentials>`
+     */
+    getAuthorizationHeader(): string;
+    /**
+     * Returns the full set of HTTP headers required for authenticated API requests.
+     *
+     * @returns An object containing `Authorization`, `Content-Type`, and `Accept` headers
+     */
+    getHeaders(): Record<string, string>;
+}
+
+export { BitbucketClient, type BitbucketClientOptions, type BitbucketCommit, type BitbucketCommitAuthor, type BitbucketParticipant, type BitbucketProject, type BitbucketPullRequest, type BitbucketRef, type BitbucketRepository, type CommitsParams, type PagedResponse, type PaginationParams, ProjectResource, type ProjectsParams, type PullRequestsParams, type ReposParams, RepositoryResource, Security };