Merge pull request #126 from Kzoeps/location-refactor

refactor(sdk-core): extract URI parsing/record helpers, fix blob upload and scope validation

Author: aspiers

.beads/.gitignore

@@ -1,3 +1,7 @@
+# Dolt database directory and lock file
+dolt/
+dolt-access.lock
+
 # SQLite databases
 *.db
 *.db?*

.changeset/refactor-uri-parsing-utilities.md

@@ -0,0 +1,21 @@
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Refactor internal URI parsing and blob upload operations
+
+**Breaking:** `BlobOperationsImpl.upload()` now returns AT Protocol's `BlobRef` type instead of a plain
+`{ ref, mimeType, size }` object. Callers should access blob properties via `BlobRef` methods (e.g.
+`result.ref.toString()` for the CID string). SDS uploads now return a proper `BlobRef` instance with `ref`, `mimeType`,
+and `size` correctly populated from the server response.
+
+- Fix `validateScope` permission prefix regex to correctly accept query-param style scopes (e.g. `repo?action=create`,
+  `blob?accept=video/*`, `rpc?lxm=*`) and reject bare `atproto` with a suffix
+- Export `AT_URI_REGEX` from `@hypercerts-org/sdk-core` for direct regex usage
+- Consolidate AT-URI parsing in HypercertOperationsImpl using `parseAtUri()` utility
+- Add internal `fetchRecord<T>()` and `saveRecord()` helpers to reduce code duplication
+- Fix `AT_URI_REGEX` rkey capture group to use `[^/]+` instead of `.+` to prevent over-matching
+- Fix `fetchRecord` to throw `NetworkError` when CID is absent instead of silently using an empty string
+- Fix `saveRecord` error message formatting (was passing two arguments to `NetworkError`)
+- Remove dead `parseAndValidateUri` method
+- Eliminate redundant network fetch in `updateProject` by passing pre-fetched record to `updateCollectionRecord`

packages/sdk-core/src/auth/permissions.ts

@@ -1233,7 +1233,7 @@ export function validateScope(scope: string): {
   const invalidPermissions: string[] = [];
 
   // Pattern for valid permission prefixes
-  const validPrefixes = /^(atproto|transition:|account:|repo:|blob:?|rpc:|identity:|include:)/;
+  const validPrefixes = /^(atproto$|transition:|account:|repo[:?]|blob[:?]|rpc[:?]|identity:|include:)/;
 
   for (const permission of permissions) {
     if (!validPrefixes.test(permission)) {

packages/sdk-core/src/index.ts

@@ -38,6 +38,7 @@ export {
   parseAtUri,
   buildAtUri,
   extractRkeyFromUri,
+  AT_URI_REGEX,
   isValidAtUri,
   createStrongRef,
   createStrongRefFromResult,

packages/sdk-core/src/lexicons/utils.ts

@@ -11,6 +11,37 @@
 import type { StrongRef } from "../services/hypercerts/types.js";
 import type { CreateResult, UpdateResult } from "../repository/types.js";
 
+/**
+ * Regular expression for parsing AT-URIs.
+ *
+ * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
+ *
+ * Capture groups:
+ * - [1] did - The DID of the repository owner (e.g., "did:plc:abc123")
+ * - [2] collection - The NSID of the record type (e.g., "org.hypercerts.claim.activity")
+ * - [3] rkey - The record key (e.g., "3km2vj4kfqp2a")
+ *
+ * @example Direct regex usage
+ * ```typescript
+ * const match = AT_URI_REGEX.exec("at://did:plc:abc/org.hypercerts.claim.activity/xyz");
+ * if (match) {
+ *   const [, did, collection, rkey] = match;
+ * }
+ * ```
+ *
+ * @example Validation
+ * ```typescript
+ * if (AT_URI_REGEX.test(userInput)) {
+ *   // Valid AT-URI format
+ * }
+ * ```
+ *
+ * @remarks
+ * For most use cases, prefer using {@link parseAtUri} which provides
+ * better error messages and returns a typed object.
+ */
+export const AT_URI_REGEX = /^at:\/\/([^/]+)\/([^/]+)\/([^/]+)$/;
+
 /**
  * Components of an AT-URI (AT Protocol Uniform Resource Identifier).
  *

packages/sdk-core/src/repository/BlobOperationsImpl.ts

@@ -7,7 +7,9 @@
  * @packageDocumentation
  */
 
-import type { Agent, BlobRef } from "@atproto/api";
+import type { Agent } from "@atproto/api";
+import { BlobRef } from "@atproto/lexicon";
+import { CID } from "multiformats/cid";
 import { NetworkError } from "../core/errors.js";
 import type { BlobOperations } from "./interfaces.js";
 
@@ -168,9 +170,21 @@ export class BlobOperationsImpl implements BlobOperations {
       throw new NetworkError(`SDS blob upload failed: ${response.statusText}`);
     }
 
-    const result = await response.json();
+    // SDS returns { blob: { ref: { $link: string }, mimeType: string, size: number } }
+    // which is a JSON-serialized blob ref, not a BlobRef instance.
+    // Construct a BlobRef directly using CID.parse to preserve the size from the SDS response.
+    const result = (await response.json()) as {
+      blob: { ref: { $link: string }; mimeType: string; size: number };
+    };
 
-    return result.blob;
+    let cid: CID;
+    try {
+      cid = CID.parse(result.blob.ref.$link);
+    } catch {
+      throw new NetworkError("SDS blob upload returned an invalid blob reference");
+    }
+
+    return new BlobRef(cid, result.blob.mimeType, result.blob.size);
   }
 
   /**