@hypercerts-org/sdk-core 0.10.0-beta.5 → 0.10.0-beta.6

package/dist/types.d.ts

@@ -1,7 +1,8 @@
 import { OAuthSession, NodeSavedSession, NodeSavedState } from '@atproto/oauth-client-node';
 import { z } from 'zod';
 import { EventEmitter } from 'eventemitter3';
-import { OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, OrgHypercertsClaimRights, AppCertifiedLocation, OrgHypercertsClaimContributionDetails, OrgHypercertsClaimContributorInformation, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, OrgHypercertsHelperWorkScopeTag, OrgHypercertsClaimEvidence, OrgHypercertsDefs } from '@hypercerts-org/lexicon';
+import { OverrideProperties, SetOptional } from 'type-fest';
+import { ComAtprotoRepoStrongRef, AppCertifiedLocation, OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, OrgHypercertsClaimRights, OrgHypercertsClaimContributionDetails, OrgHypercertsClaimContributorInformation, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, OrgHypercertsHelperWorkScopeTag, OrgHypercertsClaimEvidence, OrgHypercertsDefs } from '@hypercerts-org/lexicon';
 export { BlobRef, JsonBlobRef } from '@atproto/lexicon';
 
 /**
@@ -1334,6 +1335,7 @@ interface ProgressStep {
  * @packageDocumentation
  */
 
+type StrongRef = ComAtprotoRepoStrongRef.Main;
 type HypercertClaim = OrgHypercertsClaimActivity.Main;
 type HypercertRights = OrgHypercertsClaimRights.Main;
 type HypercertContributionDetails = OrgHypercertsClaimContributionDetails.Main;
@@ -1352,85 +1354,118 @@ type HypercertLocation = AppCertifiedLocation.Main;
 /**
  * Image input for SDK operations.
  *
- * Can be either:
- * - A URI reference (for external images)
- * - A Blob to be uploaded
+ * Accepts either:
+ * - A string URI reference (for external images)
+ * - A Blob to be uploaded (will be converted to SmallImage or LargeImage)
  *
- * The SDK will convert these to the appropriate lexicon types:
- * - OrgHypercertsDefs.Uri
- * - OrgHypercertsDefs.SmallImage
- * - OrgHypercertsDefs.LargeImage
+ * The SDK will convert these inputs to the appropriate lexicon types.
  */
-type HypercertImage = {
-    type: "uri";
-    uri: string;
-} | {
-    type: "blob";
-    blob: Blob;
-};
+type HypercertImage = string | Blob;
 /**
  * Lexicon-defined image types (union of Uri and image blob types).
- * Use this when working with stored records.
+ *
+ * Used when working with stored records. Can be:
+ * - OrgHypercertsDefs.Uri - External image reference
+ * - OrgHypercertsDefs.SmallImage - Uploaded blob for avatars/thumbnails
+ * - OrgHypercertsDefs.LargeImage - Uploaded blob for banners/covers
  */
 type HypercertImageRecord = OrgHypercertsDefs.Uri | OrgHypercertsDefs.SmallImage | OrgHypercertsDefs.LargeImage;
-/** Hypercert with AT Protocol metadata */
-interface HypercertWithMetadata {
-    uri: string;
-    cid: string;
-    record: HypercertClaim;
-}
+/** Hypercert with resolved metadata */
+type HypercertWithMetadata = HypercertClaim & {
+    resolvedRights?: HypercertRights;
+    resolvedLocation?: HypercertLocation;
+};
+/** Project type alias (collection with type="project") */
+type HypercertProject = HypercertCollection & {
+    type: "project";
+};
+/** Project with resolved metadata */
+type HypercertProjectWithMetadata = HypercertCollection & {
+    resolvedLocation?: HypercertLocation;
+    resolvedActivities?: HypercertClaim[];
+};
+
+type CollectionItemInput = SetOptional<OrgHypercertsClaimCollection.Item, "$type">;
+/**
+ * Parameters for specifying a location in collection/project operations.
+ * Supports three ways to specify location:
+ *
+ * 1. **StrongRef** - Direct reference with uri and cid (no record creation)
+ * 2. **AT-URI string** - Reference to existing location record
+ * 3. **Location object** - Full location data (lpVersion, srs, locationType, location, etc.)
+ *    with optional `$type` and `createdAt` fields
+ *    where-as location field can be a Blob (e.g., GeoJSON) that will be uploaded
+ *
+ * @example Using a StrongRef (no record creation)
+ * ```typescript
+ * const location: AttachLocationParams = { uri: "at://did:plc:test/app.certified.location/abc", cid: "bafyrei..." };
+ * ```
+ *
+ * @example Using an AT-URI (fetches existing record)
+ * ```typescript
+ * const location: AttachLocationParams = "at://did:plc:test/app.certified.location/xyz";
+ * ```
+ *
+ * @example Using a location object
+ * ```typescript
+ * const location: AttachLocationParams = {
+ *   lpVersion: "1.0.0",
+ *   srs: "EPSG:4326",
+ *   locationType: "coordinate-decimal",
+ *   location: "https://locationuri.com",
+ *   name: "San Francisco",
+ * };
+ * ```
+ */
+type CreateLocationParams = OverrideProperties<SetOptional<HypercertLocation, "$type" | "createdAt">, {
+    location: string | Blob | HypercertLocation["location"];
+}>;
+type LocationParams = StrongRef | string | CreateLocationParams;
 /**
- * Project type - a HypercertCollection with type='project'.
+ * SDK input parameters for creating a collection.
+ * Derived from lexicon type with $type and createdAt removed.
+ * avatar/banner accept HypercertImage (string URI or Blob) for user convenience.
+ * Location can be provided inline or via attachLocationToCollection().
  */
-interface HypercertProject extends HypercertCollection {
-    type: "project";
-}
+type CreateCollectionParams = OverrideProperties<SetOptional<OrgHypercertsClaimCollection.Main, "$type" | "createdAt">, {
+    avatar?: HypercertImage;
+    banner?: HypercertImage;
+    items: CollectionItemInput[];
+    /**
+     * Optional location to attach to the collection.
+     * Can be:
+     * - StrongRef to reference existing location (uri + cid)
+     * - string (AT-URI) to reference existing location (CID will be fetched)
+     * - Location object to create a new location record
+     */
+    location?: LocationParams;
+}>;
 /**
- * HypercertProject with AT Protocol metadata.
+ * SDK input parameters for updating a collection.
+ * All fields are optional.
+ * avatar/banner accept HypercertImage (string URI or Blob), or null to remove.
+ * Location can be updated inline or removed with null.
  */
-interface HypercertProjectWithMetadata {
+type UpdateCollectionParams = Omit<Partial<CreateCollectionParams>, "avatar" | "banner" | "location"> & {
+    avatar?: HypercertImage | null;
+    banner?: HypercertImage | null;
+    location?: LocationParams | null;
+};
+type CreateCollectionResult = {
     uri: string;
     cid: string;
-    record: HypercertProject;
-}
+    record: HypercertCollection;
+};
 /**
- * Parameters for creating a project.
+ * SDK input parameters for creating a project.
+ * Projects are collections with type="project" (set automatically).
  */
-interface CreateProjectParams {
-    title: string;
-    shortDescription: string;
-    description?: unknown;
-    avatar?: Blob;
-    banner?: Blob;
-    activities?: Array<{
-        uri: string;
-        cid: string;
-        weight: string;
-    }>;
-    location?: {
-        uri: string;
-        cid: string;
-    };
-}
+type CreateProjectParams = CreateCollectionParams;
 /**
- * Parameters for updating a project.
+ * SDK input parameters for updating a project.
  */
-interface UpdateProjectParams {
-    title?: string;
-    shortDescription?: string;
-    description?: unknown;
-    avatar?: Blob;
-    banner?: Blob;
-    activities?: Array<{
-        uri: string;
-        cid: string;
-        weight: string;
-    }>;
-    location?: {
-        uri: string;
-        cid: string;
-    };
-}
+type UpdateProjectParams = UpdateCollectionParams;
+type CreateProjectResult = CreateCollectionResult;
 
 /**
  * Parameters for creating a new hypercert.
@@ -1569,7 +1604,7 @@ interface CreateHypercertParams {
     /**
      * Optional geographic location of the impact.
      */
-    location?: AttachLocationParams;
+    location?: LocationParams;
     /**
      * Optional list of contributions to the impact.
      *
@@ -1658,49 +1693,6 @@ interface CreateHypercertEvidenceParams {
      */
     [k: string]: unknown;
 }
-/**
- * Parameters for attaching a location to a hypercert.
- *
- * @example Using a string location
- * ```typescript
- * const params: AttachLocationParams = {
- *   lpVersion: "1.0.0",
- *   srs: "EPSG:4326",
- *   locationType: "coordinate-decimal",
- *   location: "https://locationuri.com",
- *   name: "San Francisco",
- *   description: "Project location in SF Bay Area",
- * };
- * ```
- *
- * @example Using a GeoJSON Blob
- * ```typescript
- * const geojsonBlob = new Blob(
- *   [JSON.stringify({ type: "Point", coordinates: [-122.4194, 37.7749] })],
- *   { type: "application/geo+json" }
- * );
- * const params: AttachLocationParams = {
- *   lpVersion: "1.0.0",
- *   srs: "EPSG:4326",
- *   locationType: "geojson-point",
- *   location: geojsonBlob,
- * };
- * ```
- */
-interface AttachLocationParams {
-    /** The version of the Location Protocol */
-    lpVersion: string;
-    /** The Spatial Reference System URI (e.g., http://www.opengis.net/def/crs/OGC/1.3/CRS84) that defines the coordinate system. */
-    srs: string;
-    /** An identifier for the format of the location data (e.g., coordinate-decimal, geojson-point) */
-    locationType: "coordinate-decimal" | "geojson-point" | (string & {});
-    /** Location data as either a URL string or a GeoJSON Blob */
-    location: string | Blob;
-    /** Optional name for this location */
-    name?: string;
-    /** Optional description for this location */
-    description?: string;
-}
 /**
  * Result of creating a hypercert.
  *
@@ -2049,6 +2041,33 @@ interface HypercertEvents {
         uri: string;
         cid: string;
     };
+    /**
+     * Emitted when a collection is updated.
+     */
+    collectionUpdated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a collection is deleted.
+     */
+    collectionDeleted: {
+        uri: string;
+    };
+    /**
+     * Emitted when a location is attached to a collection.
+     */
+    locationAttachedToCollection: {
+        uri: string;
+        cid: string;
+        collectionUri: string;
+    };
+    /**
+     * Emitted when a location is removed from a collection.
+     */
+    locationRemovedFromCollection: {
+        collectionUri: string;
+    };
     /**
      * Emitted when a project is created.
      */
@@ -2069,6 +2088,20 @@ interface HypercertEvents {
     projectDeleted: {
         uri: string;
     };
+    /**
+     * Emitted when a location is attached to a project.
+     */
+    locationAttachedToProject: {
+        uri: string;
+        cid: string;
+        projectUri: string;
+    };
+    /**
+     * Emitted when a location is removed from a project.
+     */
+    locationRemovedFromProject: {
+        projectUri: string;
+    };
 }
 /**
  * High-level hypercert operations.
@@ -2124,7 +2157,7 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
      */
     update(params: {
         uri: string;
-        updates: Partial<Omit<HypercertClaim, "$type" | "createdAt" | "rights">>;
+        updates: Partial<CreateHypercertParams>;
         image?: Blob | null;
     }): Promise<UpdateResult>;
     /**
@@ -2170,7 +2203,7 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
      * @param location.geojson - Optional GeoJSON blob for precise boundaries
      * @returns Promise resolving to location record result
      */
-    attachLocation(uri: string, location: AttachLocationParams): Promise<CreateResult>;
+    attachLocation(uri: string, location: LocationParams): Promise<CreateResult>;
     /**
      * Adds evidence to an existing hypercert.
      *
@@ -2219,18 +2252,9 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
      * Creates a collection of hypercerts.
      *
      * @param params - Collection parameters
-     * @returns Promise resolving to collection record result
-     */
-    createCollection(params: {
-        title: string;
-        claims: Array<{
-            uri: string;
-            cid: string;
-            weight: string;
-        }>;
-        shortDescription?: string;
-        banner?: Blob;
-    }): Promise<CreateResult>;
+     * @returns Promise resolving to collection record result with optional location URI
+     */
+    createCollection(params: CreateCollectionParams): Promise<CreateCollectionResult>;
     /**
      * Gets a collection by URI.
      *
@@ -2253,24 +2277,45 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
         cid: string;
         record: HypercertCollection;
     }>>;
+    /**
+     * Updates a collection.
+     *
+     * @param uri - AT-URI of the collection
+     * @param updates - Fields to update
+     * @returns Promise resolving to update result
+     */
+    updateCollection(uri: string, updates: UpdateCollectionParams): Promise<UpdateResult>;
+    /**
+     * Deletes a collection.
+     *
+     * @param uri - AT-URI of the collection
+     * @returns Promise resolving when deleted
+     */
+    deleteCollection(uri: string): Promise<void>;
+    /**
+     * Attaches a location to a collection.
+     *
+     * @param uri - AT-URI of the collection
+     * @param location - Location data
+     * @returns Promise resolving to location record result
+     */
+    attachLocationToCollection(uri: string, location: LocationParams): Promise<CreateResult>;
+    /**
+     * Removes a location from a collection.
+     *
+     * @param uri - AT-URI of the collection
+     * @returns Promise resolving when location is removed
+     */
+    removeLocationFromCollection(uri: string): Promise<void>;
     /**
      * Creates a project.
      *
+     * A project is a collection with type='project' and optional location sidecar.
+     *
      * @param params - Project parameters
-     * @returns Promise resolving to project record result
-     */
-    createProject(params: {
-        title: string;
-        shortDescription: string;
-        description?: unknown;
-        avatar?: Blob;
-        banner?: Blob;
-        activities?: Array<{
-            uri: string;
-            cid: string;
-            weight: string;
-        }>;
-    }): Promise<CreateResult>;
+     * @returns Promise resolving to project record result with optional location URI
+     */
+    createProject(params: CreateProjectParams): Promise<CreateProjectResult>;
     /**
      * Gets a project by URI.
      *
@@ -2304,18 +2349,7 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
      * @param updates - Fields to update
      * @returns Promise resolving to update result
      */
-    updateProject(uri: string, updates: {
-        title?: string;
-        shortDescription?: string;
-        description?: unknown;
-        avatar?: Blob | null;
-        banner?: Blob | null;
-        activities?: Array<{
-            uri: string;
-            cid: string;
-            weight: string;
-        }>;
-    }): Promise<UpdateResult>;
+    updateProject(uri: string, updates: UpdateProjectParams): Promise<UpdateResult>;
     /**
      * Deletes a project.
      *
@@ -2323,6 +2357,21 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
      * @returns Promise resolving when deleted
      */
     deleteProject(uri: string): Promise<void>;
+    /**
+     * Attaches a location to a project.
+     *
+     * @param uri - AT-URI of the project
+     * @param location - Location data
+     * @returns Promise resolving to location record result
+     */
+    attachLocationToProject(uri: string, location: LocationParams): Promise<CreateResult>;
+    /**
+     * Removes a location from a project.
+     *
+     * @param uri - AT-URI of the project
+     * @returns Promise resolving when location is removed
+     */
+    removeLocationFromProject(uri: string): Promise<void>;
 }
 /**
  * Collaborator operations for SDS access control.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercerts-org/sdk-core",
-  "version": "0.10.0-beta.5",
+  "version": "0.10.0-beta.6",
   "description": "Framework-agnostic ATProto SDK core for authentication, repository operations, and lexicon management",
   "main": "dist/index.cjs",
   "repository": {
@@ -76,8 +76,9 @@
     "@atproto/lexicon": "^0.5.1",
     "@atproto/oauth-client": "^0.5.10",
     "@atproto/oauth-client-node": "^0.3.12",
-    "@hypercerts-org/lexicon": "0.10.0-beta.10",
+    "@hypercerts-org/lexicon": "0.10.0-beta.11",
     "eventemitter3": "^5.0.1",
+    "type-fest": "^5.4.1",
     "zod": "^3.24.4"
   },
   "scripts": {