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

package/dist/index.d.ts

@@ -4,7 +4,8 @@ import { LexiconDoc as LexiconDoc$1, Lexicons } from '@atproto/lexicon';
 export { BlobRef, JsonBlobRef } from '@atproto/lexicon';
 import { Agent } from '@atproto/api';
 import { EventEmitter } from 'eventemitter3';
-import { OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, ComAtprotoRepoStrongRef, OrgHypercertsClaimRights, OrgHypercertsClaimContributionDetails, OrgHypercertsClaimContributorInformation, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, OrgHypercertsHelperWorkScopeTag, AppCertifiedLocation, AppCertifiedBadgeAward, AppCertifiedBadgeDefinition, AppCertifiedBadgeResponse, OrgHypercertsFundingReceipt, OrgHypercertsClaimEvidence, OrgHypercertsDefs } from '@hypercerts-org/lexicon';
+import { OverrideProperties, SetOptional } from 'type-fest';
+import { ComAtprotoRepoStrongRef, AppCertifiedLocation, OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, OrgHypercertsClaimRights, OrgHypercertsClaimContributionDetails, OrgHypercertsClaimContributorInformation, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, OrgHypercertsHelperWorkScopeTag, AppCertifiedBadgeAward, AppCertifiedBadgeDefinition, AppCertifiedBadgeResponse, OrgHypercertsFundingReceipt, OrgHypercertsClaimEvidence, OrgHypercertsDefs } from '@hypercerts-org/lexicon';
 export { AppCertifiedBadgeAward, AppCertifiedBadgeDefinition, AppCertifiedBadgeResponse, AppCertifiedDefs, AppCertifiedLocation, ComAtprotoRepoStrongRef, HYPERCERTS_LEXICON_DOC, HYPERCERTS_LEXICON_JSON, HYPERCERTS_NSIDS, HYPERCERTS_NSIDS_BY_TYPE, HYPERCERTS_SCHEMAS, HYPERCERTS_SCHEMA_DICT, OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, OrgHypercertsClaimContributionDetails, OrgHypercertsClaimContributorInformation, OrgHypercertsClaimEvaluation, OrgHypercertsClaimEvidence, OrgHypercertsClaimMeasurement, OrgHypercertsClaimRights, OrgHypercertsDefs, OrgHypercertsFundingReceipt, OrgHypercertsHelperWorkScopeTag, lexicons, validate } from '@hypercerts-org/lexicon';
 
 /**
@@ -1218,85 +1219,118 @@ type FundingReceipt = OrgHypercertsFundingReceipt.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">;
 /**
- * Project type - a HypercertCollection with type='project'.
+ * 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",
+ * };
+ * ```
  */
-interface HypercertProject extends HypercertCollection {
-    type: "project";
-}
+type CreateLocationParams = OverrideProperties<SetOptional<HypercertLocation, "$type" | "createdAt">, {
+    location: string | Blob | HypercertLocation["location"];
+}>;
+type LocationParams = StrongRef | string | CreateLocationParams;
+/**
+ * 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().
+ */
+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.
@@ -1435,7 +1469,7 @@ interface CreateHypercertParams {
     /**
      * Optional geographic location of the impact.
      */
-    location?: AttachLocationParams;
+    location?: LocationParams;
     /**
      * Optional list of contributions to the impact.
      *
@@ -1524,49 +1558,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.
  *
@@ -1915,6 +1906,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.
      */
@@ -1935,6 +1953,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.
@@ -1990,7 +2022,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>;
     /**
@@ -2036,7 +2068,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.
      *
@@ -2085,18 +2117,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.
      *
@@ -2119,24 +2142,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.
      *
@@ -2170,18 +2214,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.
      *
@@ -2189,6 +2222,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.
@@ -6350,4 +6398,4 @@ declare function validateScope(scope: string): {
 };
 
 export { ATPROTO_SCOPE, ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AccountActionSchema, AccountAttrSchema, AccountPermissionSchema, AuthenticationError, BaseOperations, BlobPermissionSchema, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, IdentityAttrSchema, IdentityPermissionSchema, InMemorySessionStore, InMemoryStateStore, IncludePermissionSchema, LexiconRegistry, MimeTypeSchema, NetworkError, NsidSchema, OAuthConfigSchema, OrganizationSchema, PermissionBuilder, PermissionSchema, RepoActionSchema, RepoPermissionSchema, Repository, RpcPermissionSchema, SDSRequiredError, ScopePresets, ServerConfigSchema, SessionExpiredError, TRANSITION_SCOPES, TimeoutConfigSchema, TransitionScopeSchema, ValidationError, attachSidecar, batchCreateSidecars, buildAtUri, buildScope, createATProtoSDK, createArrayField, createBlobField, createBooleanField, createDatetimeField, createIntegerField, createLexiconDoc, createNumberField, createObjectField, createRecordDef, createSidecarRecord, createStringField, createStrongRef, createStrongRefField, createStrongRefFromResult, createWithSidecars, extractRkeyFromUri, hasAllPermissions, hasAnyPermission, hasPermission, isStrongRef, isValidAtUri, mergeScopes, parseAtUri, parseScope, removePermissions, validateLexiconStructure, validateScope, validateStrongRef };
-export type { ATProtoSDKConfig, AccountAction, AccountAttr, AccountPermissionInput, AtUriComponents, AttachLocationParams, AttachSidecarParams, AuthorizeOptions, BadgeAward, BadgeDefinition, BadgeResponse, BlobOperations, BlobPermissionInput, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertEvidenceParams, CreateHypercertParams, CreateHypercertResult, CreateOrganizationParams, CreateProjectParams, CreateResult, CreateWithSidecarsParams, DID, FundingReceipt, HypercertClaim, HypercertCollection, HypercertCollectionItem, HypercertContributionDetails, HypercertContributor, HypercertContributorInformation, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertImageRecord, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertProject, HypercertProjectWithMetadata, HypercertRights, HypercertWithMetadata, HypercertWorkScopeTag, IdentityAttr, IdentityPermissionInput, IncludePermissionInput, LexiconArrayField, LexiconBlobField, LexiconBooleanField, LexiconDoc, LexiconField, LexiconFieldType, LexiconIntegerField, LexiconNumberField, LexiconObjectField, LexiconRecordDef, LexiconRefField, LexiconStringField, LexiconUnknownField, ListParams, LoggerInterface, MultiSidecarResult, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, Permission, PermissionInput, ProfileOperations, ProgressStep, RecordOperations, RepoAction, RepoPermissionInput, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, RpcPermissionInput, Session, SessionStore, SidecarRecordParams, SidecarResult, StateStore, StrongRef, TransitionScope, UpdateProjectParams, UpdateResult, ValidationResult };
+export type { ATProtoSDKConfig, AccountAction, AccountAttr, AccountPermissionInput, AtUriComponents, AttachSidecarParams, AuthorizeOptions, BadgeAward, BadgeDefinition, BadgeResponse, BlobOperations, BlobPermissionInput, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertEvidenceParams, CreateHypercertParams, CreateHypercertResult, CreateOrganizationParams, CreateProjectParams, CreateResult, CreateWithSidecarsParams, DID, FundingReceipt, HypercertClaim, HypercertCollection, HypercertCollectionItem, HypercertContributionDetails, HypercertContributor, HypercertContributorInformation, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertImageRecord, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertProject, HypercertProjectWithMetadata, HypercertRights, HypercertWithMetadata, HypercertWorkScopeTag, IdentityAttr, IdentityPermissionInput, IncludePermissionInput, LexiconArrayField, LexiconBlobField, LexiconBooleanField, LexiconDoc, LexiconField, LexiconFieldType, LexiconIntegerField, LexiconNumberField, LexiconObjectField, LexiconRecordDef, LexiconRefField, LexiconStringField, LexiconUnknownField, ListParams, LocationParams, LoggerInterface, MultiSidecarResult, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, Permission, PermissionInput, ProfileOperations, ProgressStep, RecordOperations, RepoAction, RepoPermissionInput, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, RpcPermissionInput, Session, SessionStore, SidecarRecordParams, SidecarResult, StateStore, StrongRef, TransitionScope, UpdateProjectParams, UpdateResult, ValidationResult };