@pierre/storage 0.0.9 → 0.0.11

package/README.md

@@ -51,7 +51,7 @@ The SDK generates secure URLs with JWT authentication for Git operations:
 ```typescript
 // Get URL with default permissions (git:write, git:read) and 1-year TTL
 const url = await repo.getRemoteURL();
-// Returns: https://t:JWT@your-name.git.storage/repo-id.git
+// Returns: https://t:JWT@your-name.code.storage/repo-id.git
 
 // Configure the Git remote
 console.log(`Run: git remote add origin ${url}`);
@@ -120,6 +120,88 @@ const commitDiff = await repo.getCommitDiff({
 });
 console.log(commitDiff.stats);
 console.log(commitDiff.files);
+
+// Create a commit using the streaming helper
+const fs = await import('node:fs/promises');
+const response = await repo
+  .createCommit({
+    targetRef: 'refs/heads/main',
+    commitMessage: 'Update docs',
+  })
+  .addFileFromString('docs/changelog.md', '# v2.0.1\n- add streaming SDK\n')
+  .addFile('docs/readme.md', await fs.readFile('README.md'))
+  .deletePath('docs/legacy.txt')
+  .send();
+
+console.log(response.commit.commit_sha);
+console.log(response.result.new_sha);
+console.log(response.result.old_sha); // 40 hex chars; all zeroes for brand-new branches
+```
+
+The builder exposes:
+
+- `addFile(path, source, options)` to attach bytes, async iterables, readable streams, or buffers.
+- `addFileFromString(path, contents, options)` for UTF-8 text helpers.
+- `deletePath(path)` to remove files or folders.
+- `send()` to finalize the commit and receive metadata about the new commit.
+
+`send()` resolves to `{ commit, result }`. The `result` payload mirrors the HTTP response, including
+`old_sha` (always a 40-character hex string; it is all zeroes when the target ref is being created),
+`new_sha`, `status`, and an optional `message`.
+
+**Options**
+
+- `targetRef` (required): Fully qualified ref that will receive the commit (for example
+  `refs/heads/main`).
+- `baseRef` (optional): Branch or commit that must match the remote tip; omit to fast-forward
+  unconditionally.
+- `commitMessage` (required): The commit message.
+- `author` and `committer` (optional): Include `name`, `email`, and optional ISO 8601 `date`.
+- `signal` (optional): Abort an in-flight upload with `AbortController`.
+
+> Files are chunked into 4 MiB segments under the hood, so you can stream large assets without
+> buffering them entirely in memory. File paths are normalized relative to the repository root.
+
+### Creating a new branch
+
+You can create and populate a new branch in a single request by pointing `targetRef` at the new ref
+and setting `baseRef` to the branch (or commit SHA) you want to fork from.
+
+```typescript
+const baseBranch = 'main';
+const featureBranch = 'refs/heads/feature/onboarding';
+
+await repo
+  .createCommit({
+    targetRef: featureBranch,
+    baseRef: `refs/heads/${baseBranch}`,
+    commitMessage: 'feat: add onboarding copy',
+  })
+  .addFileFromString('apps/dashboard/Onboarding.tsx', '<Onboarding />\n')
+  .send();
+```
+
+> If you omit `baseRef` while referencing a brand-new `targetRef`, the service creates an orphan
+> commit with no parent. The new branch starts from an empty tree, so only the files you include in
+> this commit will exist. Always provide `baseRef` when you need the branch to inherit history or
+> files from another branch.
+
+### Streaming Large Files
+
+The commit builder accepts any async iterable of bytes, so you can stream large assets without
+buffering:
+
+```typescript
+import { createReadStream } from 'node:fs';
+
+await repo
+  .createCommit({
+    targetRef: 'refs/heads/assets',
+    baseRef: 'refs/heads/main',
+    commitMessage: 'Upload latest design bundle',
+  })
+  .addFile('assets/design-kit.zip', createReadStream('/tmp/design-kit.zip'))
+  .send();
 ```
 
 ## API Reference

package/dist/index.cjs

@@ -9,6 +9,352 @@ var snakecaseKeys__default = /*#__PURE__*/_interopDefault(snakecaseKeys);
 
 // src/index.ts
 
+// src/commit.ts
+var MAX_CHUNK_BYTES = 4 * 1024 * 1024;
+var DEFAULT_TTL_SECONDS = 60 * 60;
+var BufferCtor = globalThis.Buffer;
+var CommitBuilderImpl = class {
+  options;
+  getAuthToken;
+  transport;
+  operations = [];
+  sent = false;
+  constructor(deps) {
+    this.options = { ...deps.options };
+    this.getAuthToken = deps.getAuthToken;
+    this.transport = deps.transport;
+    const trimmedTarget = this.options.targetRef?.trim();
+    const trimmedMessage = this.options.commitMessage?.trim();
+    if (!trimmedTarget) {
+      throw new Error("createCommit targetRef is required");
+    }
+    if (!trimmedMessage) {
+      throw new Error("createCommit commitMessage is required");
+    }
+    this.options.targetRef = trimmedTarget;
+    this.options.commitMessage = trimmedMessage;
+    if (typeof this.options.baseRef === "string") {
+      this.options.baseRef = this.options.baseRef.trim();
+    }
+  }
+  addFile(path, source, options) {
+    this.ensureNotSent();
+    const normalizedPath = this.normalizePath(path);
+    const contentId = randomContentId();
+    const mode = options?.mode ?? "100644";
+    this.operations.push({
+      path: normalizedPath,
+      contentId,
+      mode,
+      operation: "upsert",
+      streamFactory: () => toAsyncIterable(source)
+    });
+    return this;
+  }
+  addFileFromString(path, contents, options) {
+    const encoding = options?.encoding;
+    if (encoding && encoding !== "utf8" && encoding !== "utf-8") {
+      throw new Error(`Unsupported encoding "${encoding}". Only UTF-8 is supported.`);
+    }
+    const data = new TextEncoder().encode(contents);
+    return this.addFile(path, data, options);
+  }
+  deletePath(path) {
+    this.ensureNotSent();
+    const normalizedPath = this.normalizePath(path);
+    this.operations.push({
+      path: normalizedPath,
+      contentId: randomContentId(),
+      operation: "delete"
+    });
+    return this;
+  }
+  async send() {
+    this.ensureNotSent();
+    this.sent = true;
+    const metadata = this.buildMetadata();
+    const blobEntries = this.operations.filter((op) => op.operation === "upsert" && op.streamFactory).map((op) => ({
+      contentId: op.contentId,
+      chunks: chunkify(op.streamFactory())
+    }));
+    const authorization = await this.getAuthToken();
+    return this.transport.send({
+      authorization,
+      signal: this.options.signal,
+      metadata,
+      blobs: blobEntries
+    });
+  }
+  buildMetadata() {
+    const files = this.operations.map((op) => {
+      const entry = {
+        path: op.path,
+        content_id: op.contentId,
+        operation: op.operation
+      };
+      if (op.mode) {
+        entry.mode = op.mode;
+      }
+      return entry;
+    });
+    const metadata = {
+      target_ref: this.options.targetRef,
+      commit_message: this.options.commitMessage,
+      files
+    };
+    if (this.options.baseRef) {
+      metadata.base_ref = this.options.baseRef;
+    }
+    if (this.options.author) {
+      metadata.author = { ...this.options.author };
+    }
+    if (this.options.committer) {
+      metadata.committer = { ...this.options.committer };
+    }
+    return metadata;
+  }
+  ensureNotSent() {
+    if (this.sent) {
+      throw new Error("createCommit builder cannot be reused after send()");
+    }
+  }
+  normalizePath(path) {
+    if (!path || typeof path !== "string" || path.trim() === "") {
+      throw new Error("File path must be a non-empty string");
+    }
+    return path.replace(/^\//, "");
+  }
+};
+var FetchCommitTransport = class {
+  url;
+  constructor(config) {
+    const trimmedBase = config.baseUrl.replace(/\/+$/, "");
+    this.url = `${trimmedBase}/api/v${config.version}/repos/commit-pack`;
+  }
+  async send(request) {
+    const bodyIterable = buildMessageIterable(request.metadata, request.blobs);
+    const body = toRequestBody(bodyIterable);
+    const response = await fetch(this.url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${request.authorization}`,
+        "Content-Type": "application/x-ndjson",
+        Accept: "application/json"
+      },
+      body,
+      signal: request.signal
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`createCommit request failed (${response.status}): ${text}`);
+    }
+    return await response.json();
+  }
+};
+function toRequestBody(iterable) {
+  const readableStreamCtor = globalThis.ReadableStream;
+  if (typeof readableStreamCtor === "function") {
+    const iterator = iterable[Symbol.asyncIterator]();
+    return new readableStreamCtor({
+      async pull(controller) {
+        const { value, done } = await iterator.next();
+        if (done) {
+          controller.close();
+          return;
+        }
+        controller.enqueue(value);
+      },
+      async cancel(reason) {
+        if (typeof iterator.return === "function") {
+          await iterator.return(reason);
+        }
+      }
+    });
+  }
+  return iterable;
+}
+function buildMessageIterable(metadata, blobs) {
+  const encoder = new TextEncoder();
+  return {
+    async *[Symbol.asyncIterator]() {
+      yield encoder.encode(`${JSON.stringify({ metadata })}
+`);
+      for (const blob of blobs) {
+        for await (const segment of blob.chunks) {
+          const payload = {
+            blob_chunk: {
+              content_id: blob.contentId,
+              data: base64Encode(segment.chunk),
+              eof: segment.eof
+            }
+          };
+          yield encoder.encode(`${JSON.stringify(payload)}
+`);
+        }
+      }
+    }
+  };
+}
+async function* chunkify(source) {
+  let pending = null;
+  let produced = false;
+  for await (const value of source) {
+    const bytes = value;
+    if (pending && pending.byteLength === MAX_CHUNK_BYTES) {
+      yield { chunk: pending, eof: false };
+      produced = true;
+      pending = null;
+    }
+    const merged = pending ? concatChunks(pending, bytes) : bytes;
+    pending = null;
+    let cursor = merged;
+    while (cursor.byteLength > MAX_CHUNK_BYTES) {
+      const chunk = cursor.slice(0, MAX_CHUNK_BYTES);
+      cursor = cursor.slice(MAX_CHUNK_BYTES);
+      yield { chunk, eof: false };
+      produced = true;
+    }
+    pending = cursor;
+  }
+  if (pending) {
+    yield { chunk: pending, eof: true };
+    produced = true;
+  }
+  if (!produced) {
+    yield { chunk: new Uint8Array(0), eof: true };
+  }
+}
+async function* toAsyncIterable(source) {
+  if (typeof source === "string") {
+    yield new TextEncoder().encode(source);
+    return;
+  }
+  if (source instanceof Uint8Array) {
+    yield source;
+    return;
+  }
+  if (source instanceof ArrayBuffer) {
+    yield new Uint8Array(source);
+    return;
+  }
+  if (ArrayBuffer.isView(source)) {
+    yield new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+    return;
+  }
+  if (isBlobLike(source)) {
+    const stream = source.stream();
+    if (isAsyncIterable(stream)) {
+      for await (const chunk of stream) {
+        yield ensureUint8Array(chunk);
+      }
+      return;
+    }
+    if (isReadableStreamLike(stream)) {
+      yield* readReadableStream(stream);
+      return;
+    }
+  }
+  if (isAsyncIterable(source)) {
+    for await (const chunk of source) {
+      yield ensureUint8Array(chunk);
+    }
+    return;
+  }
+  if (isIterable(source)) {
+    for (const chunk of source) {
+      yield ensureUint8Array(chunk);
+    }
+    return;
+  }
+  throw new Error("Unsupported file source for createCommit");
+}
+async function* readReadableStream(stream) {
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) {
+        break;
+      }
+      if (value !== void 0) {
+        yield ensureUint8Array(value);
+      }
+    }
+  } finally {
+    reader.releaseLock?.();
+  }
+}
+function ensureUint8Array(value) {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (typeof value === "string") {
+    return new TextEncoder().encode(value);
+  }
+  if (BufferCtor && BufferCtor.isBuffer(value)) {
+    return value;
+  }
+  throw new Error("Unsupported chunk type; expected binary data");
+}
+function isBlobLike(value) {
+  return typeof value === "object" && value !== null && typeof value.stream === "function";
+}
+function isReadableStreamLike(value) {
+  return typeof value === "object" && value !== null && typeof value.getReader === "function";
+}
+function isAsyncIterable(value) {
+  return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+}
+function isIterable(value) {
+  return typeof value === "object" && value !== null && Symbol.iterator in value;
+}
+function concatChunks(a, b) {
+  if (a.byteLength === 0) {
+    return b;
+  }
+  if (b.byteLength === 0) {
+    return a;
+  }
+  const merged = new Uint8Array(a.byteLength + b.byteLength);
+  merged.set(a, 0);
+  merged.set(b, a.byteLength);
+  return merged;
+}
+function base64Encode(bytes) {
+  if (BufferCtor) {
+    return BufferCtor.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  const btoaFn = globalThis.btoa;
+  if (typeof btoaFn === "function") {
+    return btoaFn(binary);
+  }
+  throw new Error("Base64 encoding is not supported in this environment");
+}
+function randomContentId() {
+  const cryptoObj = globalThis.crypto;
+  if (cryptoObj && typeof cryptoObj.randomUUID === "function") {
+    return cryptoObj.randomUUID();
+  }
+  const random = Math.random().toString(36).slice(2);
+  return `cid-${Date.now().toString(36)}-${random}`;
+}
+function createCommitBuilder(deps) {
+  return new CommitBuilderImpl(deps);
+}
+function resolveCommitTtlSeconds(options) {
+  return typeof options?.ttl === "number" && options.ttl > 0 ? options.ttl : DEFAULT_TTL_SECONDS;
+}
+
 // src/fetch.ts
 var ApiFetcher = class {
   constructor(API_BASE_URL2, version) {
@@ -238,8 +584,8 @@ async function validateWebhook(payload, headers, secret, options = {}) {
 }
 
 // src/index.ts
-var API_BASE_URL = "https://api.git.storage";
-var STORAGE_BASE_URL = "git.storage";
+var API_BASE_URL = "https://api.code.storage";
+var STORAGE_BASE_URL = "code.storage";
 var API_VERSION = 1;
 var apiInstanceMap = /* @__PURE__ */ new Map();
 function getApiInstance(baseUrl, version) {
@@ -371,7 +717,7 @@ var RepoImpl = class {
     const response = await this.api.get({ path: "commit", params }, jwt);
     return await response.json();
   }
-  async repull(options) {
+  async pullUpstream(options) {
     const jwt = await this.generateJWT(this.id, {
       permissions: ["git:write"],
       ttl: options?.ttl ?? 1 * 60 * 60
@@ -381,12 +727,28 @@ var RepoImpl = class {
     if (options.ref) {
       body.ref = options.ref;
     }
-    const response = await this.api.post({ path: "repos/repull", body }, jwt);
+    const response = await this.api.post({ path: "repos/pull-upstream", body }, jwt);
     if (response.status !== 202) {
-      throw new Error(`Repull failed: ${response.status} ${await response.text()}`);
+      throw new Error(`Pull Upstream failed: ${response.status} ${await response.text()}`);
     }
     return;
   }
+  createCommit(options) {
+    const version = this.options.apiVersion ?? API_VERSION;
+    const baseUrl = this.options.apiBaseUrl ?? API_BASE_URL;
+    const transport = new FetchCommitTransport({ baseUrl, version });
+    const ttlSeconds = resolveCommitTtlSeconds(options);
+    const builderOptions = { ...options, ttl: ttlSeconds };
+    const getAuthToken = () => this.generateJWT(this.id, {
+      permissions: ["git:write"],
+      ttl: ttlSeconds
+    });
+    return createCommitBuilder({
+      options: builderOptions,
+      getAuthToken,
+      transport
+    });
+  }
 };
 var GitStorage = class _GitStorage {
   static overrides = {};