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

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 import { OAuthSession, NodeSavedSession, NodeSavedState } from '@atproto/oauth-client-node';
 import { z } from 'zod';
 import { EventEmitter } from 'eventemitter3';
-import { OrgHypercertsClaimEvidence, OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, OrgHypercertsClaimRights, AppCertifiedLocation, OrgHypercertsClaimContribution, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, OrgHypercertsDefs } from '@hypercerts-org/lexicon';
+import { OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, OrgHypercertsClaimRights, AppCertifiedLocation, OrgHypercertsClaimContributionDetails, OrgHypercertsClaimContributorInformation, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, OrgHypercertsHelperWorkScopeTag, OrgHypercertsClaimEvidence, OrgHypercertsDefs } from '@hypercerts-org/lexicon';
 export { BlobRef, JsonBlobRef } from '@atproto/lexicon';
 
 /**
@@ -738,22 +738,28 @@ interface LoggerInterface {
  * Zod schema for OAuth configuration validation.
  *
  * @remarks
- * All URLs must be valid and use HTTPS in production. The `jwkPrivate` field
- * should contain the private key in JWK (JSON Web Key) format as a string.
+ * All URLs must be valid and use HTTPS in production. For local development,
+ * HTTP loopback URLs (localhost, 127.0.0.1, [::1]) are allowed.
+ * The `jwkPrivate` field should contain the private key in JWK (JSON Web Key) format as a string.
  */
 declare const OAuthConfigSchema: z.ZodObject<{
     /**
      * URL to the OAuth client metadata JSON document.
      * This document describes your application to the authorization server.
      *
+     * For local development, you can use `http://localhost/` as a loopback client.
+     *
      * @see https://atproto.com/specs/oauth#client-metadata
      */
-    clientId: z.ZodString;
+    clientId: z.ZodEffects<z.ZodString, string, string>;
     /**
      * URL where users are redirected after authentication.
      * Must match one of the redirect URIs in your client metadata.
+     *
+     * For local development, you can use HTTP loopback URLs like
+     * `http://127.0.0.1:3000/callback` or `http://localhost:3000/callback`.
      */
-    redirectUri: z.ZodString;
+    redirectUri: z.ZodEffects<z.ZodString, string, string>;
     /**
      * OAuth scopes to request, space-separated.
      *
@@ -787,8 +793,11 @@ declare const OAuthConfigSchema: z.ZodObject<{
     /**
      * URL to your public JWKS (JSON Web Key Set) endpoint.
      * Used by the authorization server to verify your client's signatures.
+     *
+     * For local development, you can serve JWKS from a loopback URL like
+     * `http://127.0.0.1:3000/.well-known/jwks.json`.
      */
-    jwksUri: z.ZodString;
+    jwksUri: z.ZodEffects<z.ZodString, string, string>;
     /**
      * Private JWK (JSON Web Key) as a JSON string.
      * Used for signing DPoP proofs and client assertions.
@@ -798,40 +807,78 @@ declare const OAuthConfigSchema: z.ZodObject<{
      * Typically loaded from environment variables or a secrets manager.
      */
     jwkPrivate: z.ZodString;
+    /**
+     * Enable development mode features (optional).
+     *
+     * When true, suppresses warnings about using HTTP loopback URLs.
+     * Should be set to true for local development to reduce console noise.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * oauth: {
+     *   clientId: "http://localhost/",
+     *   redirectUri: "http://127.0.0.1:3000/callback",
+     *   // ... other config
+     *   developmentMode: true, // Suppress loopback warnings
+     * }
+     * ```
+     */
+    developmentMode: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     clientId: string;
     redirectUri: string;
     scope: string;
     jwksUri: string;
     jwkPrivate: string;
+    developmentMode?: boolean | undefined;
 }, {
     clientId: string;
     redirectUri: string;
     scope: string;
     jwksUri: string;
     jwkPrivate: string;
+    developmentMode?: boolean | undefined;
 }>;
 /**
  * Zod schema for server URL configuration.
  *
  * @remarks
  * At least one server (PDS or SDS) should be configured for the SDK to be useful.
+ * For local development, HTTP loopback URLs are allowed.
  */
 declare const ServerConfigSchema: z.ZodObject<{
     /**
      * Personal Data Server URL - the user's own AT Protocol server.
      * This is the primary server for user data operations.
      *
-     * @example "https://bsky.social"
+     * @example Production
+     * ```typescript
+     * pds: "https://bsky.social"
+     * ```
+     *
+     * @example Local development
+     * ```typescript
+     * pds: "http://localhost:2583"
+     * ```
      */
-    pds: z.ZodOptional<z.ZodString>;
+    pds: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     /**
      * Shared Data Server URL - for collaborative data storage.
      * Required for collaborator and organization operations.
      *
-     * @example "https://sds.hypercerts.org"
+     * @example Production
+     * ```typescript
+     * sds: "https://sds.hypercerts.org"
+     * ```
+     *
+     * @example Local development
+     * ```typescript
+     * sds: "http://127.0.0.1:2584"
+     * ```
      */
-    sds: z.ZodOptional<z.ZodString>;
+    sds: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
     pds?: string | undefined;
     sds?: string | undefined;
@@ -877,14 +924,19 @@ declare const ATProtoSDKConfigSchema: z.ZodObject<{
          * URL to the OAuth client metadata JSON document.
          * This document describes your application to the authorization server.
          *
+         * For local development, you can use `http://localhost/` as a loopback client.
+         *
          * @see https://atproto.com/specs/oauth#client-metadata
          */
-        clientId: z.ZodString;
+        clientId: z.ZodEffects<z.ZodString, string, string>;
         /**
          * URL where users are redirected after authentication.
          * Must match one of the redirect URIs in your client metadata.
+         *
+         * For local development, you can use HTTP loopback URLs like
+         * `http://127.0.0.1:3000/callback` or `http://localhost:3000/callback`.
          */
-        redirectUri: z.ZodString;
+        redirectUri: z.ZodEffects<z.ZodString, string, string>;
         /**
          * OAuth scopes to request, space-separated.
          *
@@ -918,8 +970,11 @@ declare const ATProtoSDKConfigSchema: z.ZodObject<{
         /**
          * URL to your public JWKS (JSON Web Key Set) endpoint.
          * Used by the authorization server to verify your client's signatures.
+         *
+         * For local development, you can serve JWKS from a loopback URL like
+         * `http://127.0.0.1:3000/.well-known/jwks.json`.
          */
-        jwksUri: z.ZodString;
+        jwksUri: z.ZodEffects<z.ZodString, string, string>;
         /**
          * Private JWK (JSON Web Key) as a JSON string.
          * Used for signing DPoP proofs and client assertions.
@@ -929,34 +984,71 @@ declare const ATProtoSDKConfigSchema: z.ZodObject<{
          * Typically loaded from environment variables or a secrets manager.
          */
         jwkPrivate: z.ZodString;
+        /**
+         * Enable development mode features (optional).
+         *
+         * When true, suppresses warnings about using HTTP loopback URLs.
+         * Should be set to true for local development to reduce console noise.
+         *
+         * @default false
+         *
+         * @example
+         * ```typescript
+         * oauth: {
+         *   clientId: "http://localhost/",
+         *   redirectUri: "http://127.0.0.1:3000/callback",
+         *   // ... other config
+         *   developmentMode: true, // Suppress loopback warnings
+         * }
+         * ```
+         */
+        developmentMode: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         clientId: string;
         redirectUri: string;
         scope: string;
         jwksUri: string;
         jwkPrivate: string;
+        developmentMode?: boolean | undefined;
     }, {
         clientId: string;
         redirectUri: string;
         scope: string;
         jwksUri: string;
         jwkPrivate: string;
+        developmentMode?: boolean | undefined;
     }>;
     servers: z.ZodOptional<z.ZodObject<{
         /**
          * Personal Data Server URL - the user's own AT Protocol server.
          * This is the primary server for user data operations.
          *
-         * @example "https://bsky.social"
+         * @example Production
+         * ```typescript
+         * pds: "https://bsky.social"
+         * ```
+         *
+         * @example Local development
+         * ```typescript
+         * pds: "http://localhost:2583"
+         * ```
          */
-        pds: z.ZodOptional<z.ZodString>;
+        pds: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         /**
          * Shared Data Server URL - for collaborative data storage.
          * Required for collaborator and organization operations.
          *
-         * @example "https://sds.hypercerts.org"
+         * @example Production
+         * ```typescript
+         * sds: "https://sds.hypercerts.org"
+         * ```
+         *
+         * @example Local development
+         * ```typescript
+         * sds: "http://127.0.0.1:2584"
+         * ```
          */
-        sds: z.ZodOptional<z.ZodString>;
+        sds: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     }, "strip", z.ZodTypeAny, {
         pds?: string | undefined;
         sds?: string | undefined;
@@ -989,6 +1081,7 @@ declare const ATProtoSDKConfigSchema: z.ZodObject<{
         scope: string;
         jwksUri: string;
         jwkPrivate: string;
+        developmentMode?: boolean | undefined;
     };
     servers?: {
         pds?: string | undefined;
@@ -1005,6 +1098,7 @@ declare const ATProtoSDKConfigSchema: z.ZodObject<{
         scope: string;
         jwksUri: string;
         jwkPrivate: string;
+        developmentMode?: boolean | undefined;
     };
     servers?: {
         pds?: string | undefined;
@@ -1242,12 +1336,18 @@ interface ProgressStep {
 
 type HypercertClaim = OrgHypercertsClaimActivity.Main;
 type HypercertRights = OrgHypercertsClaimRights.Main;
-type HypercertContribution = OrgHypercertsClaimContribution.Main;
+type HypercertContributionDetails = OrgHypercertsClaimContributionDetails.Main;
+type HypercertContributorInformation = OrgHypercertsClaimContributorInformation.Main;
+/** Contributor entry in an activity - can be inline or reference external records */
+type HypercertContributor = OrgHypercertsClaimActivity.Contributor;
 type HypercertMeasurement = OrgHypercertsClaimMeasurement.Main;
 type HypercertEvaluation = OrgHypercertsClaimEvaluation.Main;
 type HypercertEvidence = OrgHypercertsClaimEvidence.Main;
 type HypercertCollection = OrgHypercertsClaimCollection.Main;
-type HypercertCollectionClaimItem = OrgHypercertsClaimActivity.ActivityWeight;
+/** Collection item with optional weight */
+type HypercertCollectionItem = OrgHypercertsClaimCollection.Item;
+/** Work scope tag for creating reusable scope atoms */
+type HypercertWorkScopeTag = OrgHypercertsHelperWorkScopeTag.Main;
 type HypercertLocation = AppCertifiedLocation.Main;
 /**
  * Image input for SDK operations.
@@ -1279,6 +1379,58 @@ interface HypercertWithMetadata {
     cid: string;
     record: HypercertClaim;
 }
+/**
+ * Project type - a HypercertCollection with type='project'.
+ */
+interface HypercertProject extends HypercertCollection {
+    type: "project";
+}
+/**
+ * HypercertProject with AT Protocol metadata.
+ */
+interface HypercertProjectWithMetadata {
+    uri: string;
+    cid: string;
+    record: HypercertProject;
+}
+/**
+ * Parameters for creating a project.
+ */
+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;
+    };
+}
+/**
+ * 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;
+    };
+}
 
 /**
  * Parameters for creating a new hypercert.
@@ -1360,14 +1512,12 @@ interface CreateHypercertParams {
     description: string;
     /**
      * Scope of work or impact area.
-     * Logical scope of the work using label-based conditions. All labels in `withinAllOf` must apply; at least one label in `withinAnyOf` must apply if provided; no label in `withinNoneOf` may apply.
+     * Logical scope of the work using label-based conditions.
      *
-     * @example "Climate Action", "Education", "Healthcare"
+     * @example WorkScopeAll with atom references
      */
-    workScope?: {
-        withinAllOf?: string[];
-        withinAnyOf?: string[];
-        withinNoneOf?: string[];
+    workScope?: OrgHypercertsDefs.WorkScopeAll | OrgHypercertsDefs.WorkScopeAny | OrgHypercertsDefs.WorkScopeNot | OrgHypercertsDefs.WorkScopeAtom | {
+        $type: string;
     };
     /**
      * Start date of the work period.
@@ -1419,34 +1569,7 @@ interface CreateHypercertParams {
     /**
      * Optional geographic location of the impact.
      */
-    location?: {
-        /**
-         * Location value/address.
-         *
-         * @example "San Francisco, CA, USA"
-         */
-        value: string;
-        /**
-         * Human-readable location name.
-         *
-         * @example "SF Bay Area"
-         */
-        name?: string;
-        /**
-         * Description of the location scope.
-         */
-        description?: string;
-        /**
-         * Spatial Reference System identifier (required if location is provided).
-         *
-         * @example "EPSG:4326" for WGS84
-         */
-        srs: string;
-        /**
-         * GeoJSON file as a Blob for precise boundaries.
-         */
-        geojson?: Blob;
-    };
+    location?: AttachLocationParams;
     /**
      * Optional list of contributions to the impact.
      *
@@ -1471,7 +1594,7 @@ interface CreateHypercertParams {
     /**
      * Optional evidence supporting the impact claim.
      */
-    evidence?: HypercertEvidence[];
+    evidence?: Array<Omit<CreateHypercertEvidenceParams, "subjectUri">>;
     /**
      * Optional callback for progress updates during creation.
      *
@@ -1496,6 +1619,88 @@ interface CreateOrganizationParams {
      */
     description?: string;
 }
+/**
+ * Input params for creating Hypercert evidence.
+ *
+ * Based on `org.hypercerts.claim.evidence` but:
+ * - removes: $type, createdAt, subject, content
+ * - adds: subjectUri, content (string | Blob)
+ */
+interface CreateHypercertEvidenceParams {
+    /**
+     * URI for the subject this evidence is attached to.
+     */
+    subjectUri: string;
+    /**
+     * Evidence content.
+     * - string: should be a URI.
+     * - Blob: binary payload (e.g. image/pdf)
+     */
+    content: string | Blob;
+    /**
+     * Title to describe the nature of the evidence.
+     */
+    title: string;
+    /**
+     * Short description explaining what this evidence shows.
+     */
+    shortDescription?: string;
+    /**
+     * Longer description describing the evidence in more detail.
+     */
+    description?: string;
+    /**
+     * How this evidence relates to the subject.
+     */
+    relationType?: "supports" | "challenges" | "clarifies" | (string & {});
+    /**
+     * Any additional custom fields supported by the record.
+     */
+    [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.
  *
@@ -1526,6 +1731,10 @@ interface CreateHypercertResult {
      * AT-URIs of contribution records, if contributions were provided.
      */
     contributionUris?: string[];
+    /**
+     * AT-URIs of evidence records, if evidence was provided.
+     */
+    evidenceUris?: string[];
 }
 /**
  * Low-level record operations for AT Protocol CRUD.
@@ -1840,6 +2049,26 @@ interface HypercertEvents {
         uri: string;
         cid: string;
     };
+    /**
+     * Emitted when a project is created.
+     */
+    projectCreated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a project is updated.
+     */
+    projectUpdated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a project is deleted.
+     */
+    projectDeleted: {
+        uri: string;
+    };
 }
 /**
  * High-level hypercert operations.
@@ -1941,21 +2170,14 @@ 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: {
-        value: string;
-        name?: string;
-        description?: string;
-        srs: string;
-        geojson?: Blob;
-    }): Promise<CreateResult>;
+    attachLocation(uri: string, location: AttachLocationParams): Promise<CreateResult>;
     /**
      * Adds evidence to an existing hypercert.
      *
-     * @param uri - AT-URI of the hypercert
-     * @param evidence - Array of evidence items to add
+     * @param evidence - Evidence item to add
      * @returns Promise resolving to update result
      */
-    addEvidence(uri: string, evidence: HypercertEvidence[]): Promise<UpdateResult>;
+    addEvidence(evidence: CreateHypercertEvidenceParams): Promise<UpdateResult>;
     /**
      * Creates a contribution record.
      *
@@ -2007,7 +2229,7 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
             weight: string;
         }>;
         shortDescription?: string;
-        coverPhoto?: Blob;
+        banner?: Blob;
     }): Promise<CreateResult>;
     /**
      * Gets a collection by URI.
@@ -2031,6 +2253,76 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
         cid: string;
         record: HypercertCollection;
     }>>;
+    /**
+     * Creates a project.
+     *
+     * @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>;
+    /**
+     * Gets a project by URI.
+     *
+     * Projects are collections with type='project'.
+     *
+     * @param uri - AT-URI of the project
+     * @returns Promise resolving to project data (as collection)
+     */
+    getProject(uri: string): Promise<{
+        uri: string;
+        cid: string;
+        record: HypercertCollection;
+    }>;
+    /**
+     * Lists projects with pagination.
+     *
+     * Projects are collections with type='project'.
+     *
+     * @param params - Optional pagination parameters
+     * @returns Promise resolving to paginated list
+     */
+    listProjects(params?: ListParams): Promise<PaginatedList<{
+        uri: string;
+        cid: string;
+        record: HypercertCollection;
+    }>>;
+    /**
+     * Updates a project.
+     *
+     * @param uri - AT-URI of the project
+     * @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>;
+    /**
+     * Deletes a project.
+     *
+     * @param uri - AT-URI of the project
+     * @returns Promise resolving when deleted
+     */
+    deleteProject(uri: string): Promise<void>;
 }
 /**
  * Collaborator operations for SDS access control.
@@ -2250,4 +2542,4 @@ interface AuthorizeOptions {
 }
 
 export { ATProtoSDKConfigSchema, CollaboratorPermissionsSchema, CollaboratorSchema, OAuthConfigSchema, OrganizationSchema, ServerConfigSchema, TimeoutConfigSchema };
-export type { ATProtoSDKConfig, AuthorizeOptions, BlobOperations, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertParams, CreateHypercertResult, CreateResult, DID, HypercertClaim, HypercertCollection, HypercertCollectionClaimItem, HypercertContribution, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertImageRecord, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertRights, HypercertWithMetadata, ListParams, LoggerInterface, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, ProfileOperations, ProgressStep, RecordOperations, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, Session, SessionStore, StateStore, UpdateResult };
+export type { ATProtoSDKConfig, AuthorizeOptions, BlobOperations, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertParams, CreateHypercertResult, CreateProjectParams, CreateResult, DID, HypercertClaim, HypercertCollection, HypercertCollectionItem, HypercertContributionDetails, HypercertContributor, HypercertContributorInformation, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertImageRecord, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertProject, HypercertProjectWithMetadata, HypercertRights, HypercertWithMetadata, HypercertWorkScopeTag, ListParams, LoggerInterface, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, ProfileOperations, ProgressStep, RecordOperations, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, Session, SessionStore, StateStore, UpdateProjectParams, UpdateResult };