Merge pull request #101 from aspiers/add-location

Author: aspiers

.changeset/align-collection-project-types.md

@@ -0,0 +1,72 @@
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+feat: align collection/project types with lexicon + add inline location support
+
+This is a BREAKING change.
+
+**Type Alignment with Lexicon:**
+
+- Changed `createCollection` to use lexicon-aligned `items` array instead of `claims`
+- Updated avatar/banner handling to use proper lexicon union types
+- Simplified project methods to delegate to collection methods
+- Added `CreateCollectionParams`, `UpdateCollectionParams`, and result types derived from lexicon
+- Improved type safety by deriving SDK input types from lexicon definitions
+
+**Inline Location Support:**
+
+`AttachLocationParams` now 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 to create a new location record
+
+**Changes:**
+
+- Add `AttachLocationParams` union type supporting StrongRef, string URI, or location object
+- Add optional `location` field to `CreateCollectionParams`
+- Add optional `location` field to `UpdateCollectionParams` (supports `null` to remove)
+- Update `CreateCollectionResult` to include optional `locationUri` field
+- Implement location handling in `createCollection()` - supports all three forms
+- Add tests for collection creation with StrongRef, string URI, and location object
+
+**Example Usage:**
+
+```typescript
+// Create a project with location (StrongRef - direct reference)
+const project = await repo.hypercerts.createProject({
+  title: "Climate Initiative",
+  items: [...],
+  location: { uri: "at://did:plc:alice/app.certified.location/abc", cid: "bafy..." },
+});
+
+// Create with location (AT-URI string - fetches CID)
+const project2 = await repo.hypercerts.createProject({
+  title: "Forest Project",
+  items: [...],
+  location: "at://did:plc:bob/app.certified.location/xyz",
+});
+
+// Create with location (location object - creates new record)
+const project3 = await repo.hypercerts.createProject({
+  title: "Ocean Project",
+  items: [...],
+  location: {
+    lpVersion: "1.0",
+    srs: "EPSG:4326",
+    locationType: "coordinate-decimal",
+    location: "37.7749, -122.4194",
+  },
+});
+
+// Update project to change location
+await repo.hypercerts.updateProject(project.uri, {
+  location: "at://did:plc:alice/app.certified.location/new",
+});
+
+// Remove location
+await repo.hypercerts.updateProject(project.uri, {
+  location: null,
+});
+```

.claude/settings.json

@@ -7,6 +7,7 @@
       "Bash(pnpm lint:*)",
       "Bash(pnpm test:*)",
       "Bash(pnpm typecheck:*)"
-    ]
+    ],
+    "deny": ["Bash(npm:*)", "Bash(yarn:*)"]
   }
 }

.claude/skills/writing-changesets/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: writing-changesets
+description:
+  Create changeset files for user-facing changes. Use when making API changes, modifying types, adding features, or any
+  change that affects package consumers.
+---
+
+# Writing Changesets
+
+Create a changeset file to document user-facing changes for release.
+
+## When to Use
+
+Add a changeset when making changes that affect consumers:
+
+- Adding new SDK methods or operations (createProject, addEvidence, etc.)
+- Modifying existing API signatures (breaking or non-breaking)
+- Changing TypeScript type exports or interfaces
+- Adding new React hooks or components
+- Renaming any exported constants, types, functions, or hooks
+- Changing behavior of existing operations
+- Bug fixes that affect external behavior
+- Any change that requires a version bump or affects package consumers
+
+Skip changesets for internal changes (build scripts, tests, refactoring, documentation only).
+
+## Packages
+
+The SDK has two publishable packages:
+
+- `@hypercerts-org/sdk-core` - Core SDK
+- `@hypercerts-org/sdk-react` - React hooks etc.
+
+## Format
+
+Create in `.changeset/` a Markdown file with a descriptive kebab-case name (e.g., `fix-collection-type-alignment.md`) in
+this format:
+
+```markdown
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Align collection/project CRUD types with lexicon definitions
+```
+
+For changes affecting both packages:
+
+```markdown
+---
+"@hypercerts-org/sdk-core": minor
+"@hypercerts-org/sdk-react": minor
+---
+
+Add comprehensive project support to SDK
+
+**Core SDK (`@hypercerts-org/sdk-core`):**
+
+- Add project CRUD operations (createProject, getProject, listProjects)
+- Add project events (projectCreated, projectUpdated, projectDeleted)
+- Support for avatar and banner blob uploads
+
+**React SDK (`@hypercerts-org/sdk-react`):**
+
+- Add useProjects and useProject hooks
+- Project query keys for cache management
+- TypeScript types for projects
+```
+
+### Frontmatter Fields
+
+There should be a frontmatter field for each package being changed. The field name should be the package name, and the
+field value should be one of the following change types:
+
+- `patch` - Bug fixes, non-breaking changes
+- `minor` - New features, non-breaking additions (also breaking changes if the version in `package.json` is still 0.x.y)
+- `major` - Breaking changes (_ONLY_ use if the version in `package.json` is already greater than 0.x.y)
+
+**Current versions are 0.x.y, so use `minor` for breaking changes.**
+
+### Description
+
+In the body after the frontmatter field(s), write a clear, concise description following conventional commit style.
+Focus on what changed and why. For multi-package changes, use sections to separate changes.
+
+## Example Changesets
+
+**New SDK feature:**
+
+```markdown
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Add project CRUD operations to repository interface
+```
+
+**API signature change:**
+
+```markdown
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Evidence records are now created separately instead of being embedded inline in hypercerts
+
+**Breaking Changes:**
+
+- Evidence is no longer embedded in the hypercert record - use `result.evidenceUris` to access evidence record URIs
+- `addEvidence()` now accepts a single `CreateHypercertEvidenceParams` object instead of
+  `(uri: string, evidence: HypercertEvidence[])`
+```
+
+**Type/interface change:**
+
+```markdown
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Align collection/project CRUD types with lexicon definitions
+
+- Update CreateCollectionParams to match lexicon schema
+- Add CreateCollectionResult type with optional location URI
+- Simplify project operations to delegate to collection operations
+```
+
+**React hook addition:**
+
+```markdown
+---
+"@hypercerts-org/sdk-react": minor
+---
+
+Add useProjects and useProject hooks for project management
+```
+
+**Bug fix:**
+
+```markdown
+---
+"@hypercerts-org/sdk-core": patch
+---
+
+Fix SDS routing for organization endpoints
+```
+
+## Key Files
+
+- `.changeset/config.json` - Changeset configuration
+- Existing changeset files in `.changeset/` - Reference for naming and format
+- `package.json` - Contains version and release scripts
+- `packages/sdk-core/package.json` - Core SDK version
+- `packages/sdk-react/package.json` - React SDK version

.gitignore

@@ -22,4 +22,5 @@ yarn-error.log*
 /.idea
 stats.html
 coverage/
-.npmrc
+.npmrc
+tmp/

AGENTS.md

@@ -217,6 +217,38 @@ Use the error hierarchy in `sdk-core/src/core/errors.ts`:
 - Test files: `*.test.ts` in `tests/` directory
 - Use fixtures from `tests/utils/fixtures.ts`
 
+### SDK Type Design Principles
+
+- Types like `HypercertClaim` should always be used rather than underlying types like `OrgHypercertsClaimActivity.Main`
+  which are exported from the lexicons package
+
+- Whenever an SDK method creates a record, there should be a corresponding type like `CreateCollectionParams` defined,
+  which is derived from `HypercertCollection`, but with `$type` and `createdAt` made optional. Then the method should
+  ensure that those are auto-populated if missing.
+
+- For any methods which can refer to a _potentially_ existing record, e.g. update methods or attach methods like
+  `attachLocationToProject()`, then the user should be able to reference that object in three different ways:
+  1. provide an AT-URI pointing to an existing record
+  2. provide a StrongRef pointing to an existing record
+  3. provide an object of a type named like `Create*Params` where \* can be Collection / Activity etc. as appropriate
+
+  These possibilities should be a union type called something like `CollectionParams`.
+
+- There should also be types like `UpdateCollectionParams` which should be a `Partial` allowing the update methods to
+  perform selective updates on just some parts of the record.
+
+- So in summary, for each lexicon entity type, there should be five types, e.g. for the `org.hypercerts.claim.rights`
+  lexicon there should be:
+  1. `OrgHypercertsClaimRights.Main` (from the lexicon package)
+  2. `HypercertRights` - the same as 1, as syntactic sugar defined by the SDK. These should all be defined in the same
+     place in the same file.
+  3. `CreateRightsParams` - `SetOptional<HypercertRights, "$type" | "createdAt">` should be the basis for this
+     definition. However if the lexicon contains strongRefs to other lexicons, this should be further wrapped with
+     `OverrideProperties` from the `type-fest` package to replace any nested objects with the equivalent `Create*Params`
+     type, so that creation of multiple records can be achieved by calling a single create method for the main record.
+  4. `UpdateRightsParams` - `Partial<CreateRightsParams>`
+  5. `RightsParams` - union type `string | StrongRef | CreateRightsParams`
+
 ## Build Output
 
 ### sdk-core
@@ -247,23 +279,33 @@ Each entrypoint outputs:
 
 Uses [Changesets](https://github.com/changesets/changesets) for versioning.
 
-**Flow:** `feature` → `develop` (beta) → `main` (stable)
+**Branch flow:** `feature` → `develop` (beta) → `main` (stable)
 
-### Commands
+### Creating Changesets
 
-```bash
-pnpm changeset          # Add changeset (required for package changes)
-pnpm version-packages   # Apply changesets locally
-pnpm release            # Build and publish
-```
+**REQUIRED: All user-facing changes must include a changeset.**
+
+To create a changeset, use the `writing-changesets` skill.
+
+**The skill is the single source of truth for:**
+
+- When changesets are required vs optional
+- How to format changeset files correctly
+- Which packages to include in the frontmatter
+- Changeset type selection (patch/minor/major)
+- Examples for different types of changes
+
+Do not attempt to create changesets without consulting this skill first.
 
-### Branches
+### Release Branches
 
 - **develop**: Auto-publishes `@beta` tag (e.g., `0.2.0-beta.0`)
 - **main**: Creates Release PR → merge to publish `@latest`
 
 ### Before merging develop → main
 
+You should never do this unless explicitly requested by the user:
+
 ```bash
 pnpm changeset pre exit
 git add .changeset/pre.json
@@ -357,27 +399,11 @@ git commit -m "feat(hypercerts): add project CRUD operations"
 # - Block commit if build fails
 
 # 6. If prompted, add changeset for user-facing changes
-pnpm changeset
+# See "Release Process" section - use the writing-changesets skill
 git add .changeset/*.md
 git commit -m "chore: add changeset for project operations"
 ```
 
-### When to Add a Changeset
-
-Run `pnpm changeset` before pushing if your changes include:
-
-- New features or API changes
-- Bug fixes that affect users
-- Breaking changes
-- Performance improvements
-
-Skip changesets for:
-
-- Internal refactoring
-- Test-only changes
-- Documentation updates
-- Development tooling changes
-
 ## Key Files Reference
 
 ### sdk-core

eslint.config.mjs

@@ -30,6 +30,6 @@ export default [
     },
   },
   {
-    ignores: ["**/dist/**", "**/node_modules/**", "**/*.config.*", "**/.rollup.cache/**", "**/coverage/**"],
+    ignores: ["**/dist/**", "**/node_modules/**", "**/.rollup.cache/**", "**/coverage/**", "**/tmp/**"],
   },
 ];

opencode.json

@@ -7,7 +7,9 @@
       "pnpm format*": "allow",
       "pnpm lint*": "allow",
       "pnpm test*": "allow",
-      "pnpm typecheck*": "allow"
+      "pnpm typecheck*": "allow",
+      "npm *": "deny",
+      "yarn *": "deny"
     }
   }
 }