@pierre/storage 1.2.2 → 1.4.0

package/package.json

@@ -1,45 +1,45 @@
 {
-	"name": "@pierre/storage",
-	"version": "1.2.2",
-	"description": "Pierre Git Storage SDK",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/pierrecomputer/sdk"
-	},
-	"license": "MIT",
-	"type": "module",
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"require": "./dist/index.cjs",
-			"default": "./dist/index.js"
-		}
-	},
-	"files": [
-		"dist",
-		"src"
-	],
-	"scripts": {
-		"build": "tsup",
-		"dev": "tsup --watch",
-		"prepublishOnly": "pnpm build"
-	},
-	"dependencies": {
-		"jose": "^5.10.0",
-		"snakecase-keys": "^9.0.2",
-		"zod": "^3.23.8"
-	},
-	"devDependencies": {
-		"@types/node": "^22.0.0",
-		"tsup": "8.5.0",
-		"typescript": "5.8.3",
-		"vitest": "3.2.4"
-	},
-	"publishConfig": {
-		"access": "public"
-	}
+  "name": "@pierre/storage",
+  "version": "1.4.0",
+  "description": "Pierre Git Storage SDK",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pierrecomputer/sdk"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "jose": "^5.10.0",
+    "snakecase-keys": "^9.0.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "8.5.0",
+    "typescript": "5.8.3",
+    "vitest": "3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/index.ts

@@ -19,6 +19,8 @@ import {
   branchDiffResponseSchema,
   commitDiffResponseSchema,
   createBranchResponseSchema,
+  createTagResponseSchema,
+  deleteTagResponseSchema,
   errorEnvelopeSchema,
   grepResponseSchema,
   listBranchesResponseSchema,
@@ -26,6 +28,7 @@ import {
   listFilesResponseSchema,
   listFilesWithMetadataResponseSchema,
   listReposResponseSchema,
+  listTagsResponseSchema,
   noteReadResponseSchema,
   noteWriteResponseSchema,
   restoreCommitAckSchema,
@@ -44,8 +47,16 @@ import type {
   CreateBranchResult,
   CreateCommitFromDiffOptions,
   CreateCommitOptions,
+  CreateTagOptions,
+  CreateTagResponse,
+  CreateTagResult,
+  CreateGitCredentialOptions,
   CreateNoteOptions,
   CreateRepoOptions,
+  DeleteTagOptions,
+  DeleteTagResponse,
+  DeleteTagResult,
+  DeleteGitCredentialOptions,
   DeleteNoteOptions,
   DeleteRepoOptions,
   DeleteRepoResult,
@@ -54,6 +65,7 @@ import type {
   FileDiff,
   FilteredFile,
   FindOneOptions,
+  GenericGitBaseRepo,
   GetBranchDiffOptions,
   GetBranchDiffResponse,
   GetBranchDiffResult,
@@ -64,6 +76,8 @@ import type {
   GetNoteOptions,
   GetNoteResult,
   GetRemoteURLOptions,
+  GitCredential,
+  GitHubBaseRepo,
   GitStorageOptions,
   GrepFileMatch,
   GrepLine,
@@ -83,6 +97,9 @@ import type {
   ListReposOptions,
   ListReposResponse,
   ListReposResult,
+  ListTagsOptions,
+  ListTagsResponse,
+  ListTagsResult,
   NoteWriteResult,
   PullUpstreamOptions,
   RawBranchInfo,
@@ -91,11 +108,14 @@ import type {
   RawFileWithMetadata,
   RawFileDiff,
   RawFilteredFile,
+  RawTagInfo,
   RefUpdate,
   RepoOptions,
   Repo,
   RestoreCommitOptions,
   RestoreCommitResult,
+  TagInfo,
+  UpdateGitCredentialOptions,
   ValidAPIVersion,
 } from './types';
 
@@ -438,6 +458,37 @@ function transformCreateBranchResult(
   };
 }
 
+function transformTagInfo(raw: RawTagInfo): TagInfo {
+  return {
+    cursor: raw.cursor,
+    name: raw.name,
+    sha: raw.sha,
+  };
+}
+
+function transformListTagsResult(raw: ListTagsResponse): ListTagsResult {
+  return {
+    tags: raw.tags.map(transformTagInfo),
+    nextCursor: raw.next_cursor ?? undefined,
+    hasMore: raw.has_more,
+  };
+}
+
+function transformCreateTagResult(raw: CreateTagResponse): CreateTagResult {
+  return {
+    name: raw.name,
+    sha: raw.sha,
+    message: raw.message,
+  };
+}
+
+function transformDeleteTagResult(raw: DeleteTagResponse): DeleteTagResult {
+  return {
+    name: raw.name,
+    message: raw.message,
+  };
+}
+
 function transformListReposResult(raw: ListReposResponse): ListReposResult {
   return {
     repos: raw.repos.map((repo) => ({
@@ -793,6 +844,36 @@ class RepoImpl implements Repo {
     });
   }
 
+  async listTags(options?: ListTagsOptions): Promise<ListTagsResult> {
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(this.id, {
+      permissions: ['git:read'],
+      ttl,
+    });
+
+    const cursor = options?.cursor;
+    const limit = options?.limit;
+
+    let params: Record<string, string> | undefined;
+
+    if (typeof cursor === 'string' || typeof limit === 'number') {
+      params = {};
+      if (typeof cursor === 'string') {
+        params.cursor = cursor;
+      }
+      if (typeof limit === 'number') {
+        params.limit = limit.toString();
+      }
+    }
+
+    const response = await this.api.get({ path: 'repos/tags', params }, jwt);
+    const raw = listTagsResponseSchema.parse(await response.json());
+    return transformListTagsResult({
+      ...raw,
+      next_cursor: raw.next_cursor ?? undefined,
+    });
+  }
+
   async listCommits(options?: ListCommitsOptions): Promise<ListCommitsResult> {
     const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
     const jwt = await this.generateJWT(this.id, {
@@ -1209,6 +1290,57 @@ class RepoImpl implements Repo {
     return transformCreateBranchResult(raw);
   }
 
+  async createTag(options: CreateTagOptions): Promise<CreateTagResult> {
+    const name = options?.name?.trim();
+    if (!name) {
+      throw new Error('createTag name is required');
+    }
+    if (name.startsWith('refs/')) {
+      throw new Error('createTag name must not start with refs/');
+    }
+
+    const target = options?.target?.trim();
+    if (!target) {
+      throw new Error('createTag target is required');
+    }
+
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(this.id, {
+      permissions: ['git:write'],
+      ttl,
+    });
+
+    const response = await this.api.post(
+      { path: 'repos/tags', body: { name, target } },
+      jwt
+    );
+    const raw = createTagResponseSchema.parse(await response.json());
+    return transformCreateTagResult(raw);
+  }
+
+  async deleteTag(options: DeleteTagOptions): Promise<DeleteTagResult> {
+    const name = options?.name?.trim();
+    if (!name) {
+      throw new Error('deleteTag name is required');
+    }
+    if (name.startsWith('refs/')) {
+      throw new Error('deleteTag name must not start with refs/');
+    }
+
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(this.id, {
+      permissions: ['git:read', 'git:write'],
+      ttl,
+    });
+
+    const response = await this.api.delete(
+      { path: 'repos/tags', body: { name } },
+      jwt
+    );
+    const raw = deleteTagResponseSchema.parse(await response.json());
+    return transformDeleteTagResult(raw);
+  }
+
   async restoreCommit(
     options: RestoreCommitOptions
   ): Promise<RestoreCommitResult> {
@@ -1437,11 +1569,16 @@ export class GitStorage {
           ...(baseRepo.sha ? { sha: baseRepo.sha } : {}),
         };
       } else {
+        // Sync base repo: GitHub or generic git provider (gitlab, bitbucket, etc.)
+        const syncRepo = baseRepo as GitHubBaseRepo | GenericGitBaseRepo;
+        const { provider: _p, ...restSnakecased } = snakecaseKeys(
+          baseRepo as unknown as Record<string, unknown>
+        ) as Record<string, unknown>;
         baseRepoOptions = {
-          provider: 'github',
-          ...snakecaseKeys(baseRepo as unknown as Record<string, unknown>),
+          provider: syncRepo.provider ?? 'github',
+          ...restSnakecased,
         };
-        resolvedDefaultBranch = baseRepo.defaultBranch;
+        resolvedDefaultBranch = syncRepo.defaultBranch;
       }
     }
 
@@ -1590,6 +1727,96 @@ export class GitStorage {
     };
   }
 
+  /**
+   * Create a generic git credential for a repository.
+   * Used to authenticate sync operations for non-GitHub providers (GitLab, Bitbucket, etc.)
+   */
+  async createGitCredential(
+    options: CreateGitCredentialOptions
+  ): Promise<GitCredential> {
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(options.repoId, {
+      permissions: ['repo:write'],
+      ttl,
+    });
+
+    const body: Record<string, unknown> = {
+      repo_id: options.repoId,
+      password: options.password,
+    };
+    if (options.username !== undefined) {
+      body.username = options.username;
+    }
+
+    const resp = await this.api.post(
+      { path: 'repos/git-credentials', body },
+      jwt,
+      { allowedStatus: [409] }
+    );
+    if (resp.status === 409) {
+      throw new Error('A credential already exists for this repository');
+    }
+
+    const data = (await resp.json()) as { id: string };
+    return { id: data.id };
+  }
+
+  /**
+   * Update an existing generic git credential.
+   */
+  async updateGitCredential(
+    options: UpdateGitCredentialOptions
+  ): Promise<GitCredential> {
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT('org', {
+      permissions: ['repo:write'],
+      ttl,
+    });
+
+    const body: Record<string, unknown> = {
+      id: options.id,
+      password: options.password,
+    };
+    if (options.username !== undefined) {
+      body.username = options.username;
+    }
+
+    const resp = await this.api.put(
+      { path: 'repos/git-credentials', body },
+      jwt,
+      { allowedStatus: [404] }
+    );
+    if (resp.status === 404) {
+      throw new Error('Credential not found');
+    }
+
+    const data = (await resp.json()) as { id: string; created_at?: string };
+    return {
+      id: data.id,
+      ...(data.created_at ? { createdAt: data.created_at } : {}),
+    };
+  }
+
+  /**
+   * Delete a generic git credential.
+   */
+  async deleteGitCredential(options: DeleteGitCredentialOptions): Promise<void> {
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT('org', {
+      permissions: ['repo:write'],
+      ttl,
+    });
+
+    const resp = await this.api.delete(
+      { path: 'repos/git-credentials', body: { id: options.id } },
+      jwt,
+      { allowedStatus: [404] }
+    );
+    if (resp.status === 404) {
+      throw new Error('Credential not found');
+    }
+  }
+
   /**
    * Get the current configuration
    * @returns The client configuration

package/src/schemas.ts

@@ -141,6 +141,29 @@ export const createBranchResponseSchema = z.object({
   commit_sha: z.string().nullable().optional(),
 });
 
+export const tagInfoSchema = z.object({
+  cursor: z.string(),
+  name: z.string(),
+  sha: z.string(),
+});
+
+export const listTagsResponseSchema = z.object({
+  tags: z.array(tagInfoSchema),
+  next_cursor: z.string().nullable().optional(),
+  has_more: z.boolean(),
+});
+
+export const createTagResponseSchema = z.object({
+  name: z.string(),
+  sha: z.string(),
+  message: z.string(),
+});
+
+export const deleteTagResponseSchema = z.object({
+  name: z.string(),
+  message: z.string(),
+});
+
 export const refUpdateResultSchema = z.object({
   branch: z.string(),
   old_sha: z.string(),
@@ -244,6 +267,10 @@ export type GetCommitDiffResponseRaw = z.infer<typeof commitDiffResponseSchema>;
 export type CreateBranchResponseRaw = z.infer<
   typeof createBranchResponseSchema
 >;
+export type RawTagInfo = z.infer<typeof tagInfoSchema>;
+export type ListTagsResponseRaw = z.infer<typeof listTagsResponseSchema>;
+export type CreateTagResponseRaw = z.infer<typeof createTagResponseSchema>;
+export type DeleteTagResponseRaw = z.infer<typeof deleteTagResponseSchema>;
 export type CommitPackAckRaw = z.infer<typeof commitPackAckSchema>;
 export type RestoreCommitAckRaw = z.infer<typeof restoreCommitAckSchema>;
 export type GrepResponseRaw = z.infer<typeof grepResponseSchema>;

package/src/types.ts

@@ -3,6 +3,8 @@
  */
 import type {
   CreateBranchResponseRaw,
+  CreateTagResponseRaw,
+  DeleteTagResponseRaw,
   GetBranchDiffResponseRaw,
   GetCommitDiffResponseRaw,
   ListBranchesResponseRaw,
@@ -10,6 +12,7 @@ import type {
   ListFilesResponseRaw,
   ListFilesWithMetadataResponseRaw,
   ListReposResponseRaw,
+  ListTagsResponseRaw,
   NoteReadResponseRaw,
   NoteWriteResponseRaw,
   RawBranchInfo as SchemaRawBranchInfo,
@@ -20,6 +23,7 @@ import type {
   RawFilteredFile as SchemaRawFilteredFile,
   RawRepoBaseInfo as SchemaRawRepoBaseInfo,
   RawRepoInfo as SchemaRawRepoInfo,
+  RawTagInfo as SchemaRawTagInfo,
 } from './schemas';
 
 export interface OverrideableGitStorageOptions {
@@ -57,7 +61,10 @@ export interface Repo {
     options?: ListFilesWithMetadataOptions
   ): Promise<ListFilesWithMetadataResult>;
   listBranches(options?: ListBranchesOptions): Promise<ListBranchesResult>;
+  listTags(options?: ListTagsOptions): Promise<ListTagsResult>;
   listCommits(options?: ListCommitsOptions): Promise<ListCommitsResult>;
+  createTag(options: CreateTagOptions): Promise<CreateTagResult>;
+  deleteTag(options: DeleteTagOptions): Promise<DeleteTagResult>;
   getNote(options: GetNoteOptions): Promise<GetNoteResult>;
   createNote(options: CreateNoteOptions): Promise<NoteWriteResult>;
   appendNote(options: AppendNoteOptions): Promise<NoteWriteResult>;
@@ -97,7 +104,14 @@ export interface RepoOptions {
   createdAt?: string;
 }
 
-export type SupportedRepoProvider = 'github';
+export type SupportedRepoProvider =
+  | 'github'
+  | 'gitlab'
+  | 'bitbucket'
+  | 'gitea'
+  | 'forgejo'
+  | 'codeberg'
+  | 'sr.ht';
 
 export interface PublicGitHubBaseRepoAuth {
   /**
@@ -110,20 +124,59 @@ export interface GitHubBaseRepo {
   /**
    * @default github
    */
-  provider?: SupportedRepoProvider;
+  provider?: 'github';
   owner: string;
   name: string;
   defaultBranch?: string;
   auth?: PublicGitHubBaseRepoAuth;
 }
 
+export interface GenericGitBaseRepo {
+  /**
+   * The git host provider. Must be one of the supported generic git providers.
+   */
+  provider: Exclude<SupportedRepoProvider, 'github'>;
+  owner: string;
+  name: string;
+  defaultBranch?: string;
+  /**
+   * Bare hostname for self-hosted instances (e.g. "gitlab.example.com").
+   * Falls back to the provider's default host when omitted.
+   */
+  upstreamHost?: string;
+}
+
 export interface ForkBaseRepo {
   id: string;
   ref?: string;
   sha?: string;
 }
 
-export type BaseRepo = GitHubBaseRepo | ForkBaseRepo;
+export type BaseRepo = GitHubBaseRepo | ForkBaseRepo | GenericGitBaseRepo;
+
+export interface CreateGitCredentialOptions {
+  repoId: string;
+  username?: string;
+  password: string;
+  ttl?: number;
+}
+
+export interface UpdateGitCredentialOptions {
+  id: string;
+  username?: string;
+  password: string;
+  ttl?: number;
+}
+
+export interface DeleteGitCredentialOptions {
+  id: string;
+  ttl?: number;
+}
+
+export interface GitCredential {
+  id: string;
+  createdAt?: string;
+}
 
 export interface ListReposOptions extends GitStorageInvocationOptions {
   cursor?: string;
@@ -275,6 +328,51 @@ export interface CreateBranchResult {
   commitSha?: string;
 }
 
+export interface ListTagsOptions extends GitStorageInvocationOptions {
+  cursor?: string;
+  limit?: number;
+}
+
+export type RawTagInfo = SchemaRawTagInfo;
+
+export interface TagInfo {
+  cursor: string;
+  name: string;
+  sha: string;
+}
+
+export type ListTagsResponse = ListTagsResponseRaw;
+
+export interface ListTagsResult {
+  tags: TagInfo[];
+  nextCursor?: string;
+  hasMore: boolean;
+}
+
+export interface CreateTagOptions extends GitStorageInvocationOptions {
+  name: string;
+  target: string;
+}
+
+export type CreateTagResponse = CreateTagResponseRaw;
+
+export interface CreateTagResult {
+  name: string;
+  sha: string;
+  message: string;
+}
+
+export interface DeleteTagOptions extends GitStorageInvocationOptions {
+  name: string;
+}
+
+export type DeleteTagResponse = DeleteTagResponseRaw;
+
+export interface DeleteTagResult {
+  name: string;
+  message: string;
+}
+
 // List Commits API types
 export interface ListCommitsOptions extends GitStorageInvocationOptions {
   branch?: string;