Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions .agents/skills/hypercerts-org-sdk/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ name: hypercerts-org-sdk
description: "Write Hypercerts and Certified records (org.hypercerts.*, app.certified.*) to a PDS from an app with @hypercerts-org/sdk: setting up the SDK context from an authenticated @atproto/lex Client, choosing the right operation and subpath, uploading blobs, and handling write errors without duplicates. Use when app code imports @hypercerts-org/sdk, or the user wants to create, link or write hypercert-related records from an app. Not for changing the SDK's own source."
metadata:
author: hypercerts-org
version: "4"
version: "7"
---

# @hypercerts-org/sdk
Expand Down Expand Up @@ -51,6 +51,7 @@ Make a new context when the signed-in account changes. Records are always writte
| `@hypercerts-org/sdk/tag` | `createVocabularyTag`, `createWorkScopeTag`, `RecordAlreadyExistsError`, the same `Write*` errors, input/result types |
| `@hypercerts-org/sdk/feature` | `createFeature`, `RecordAlreadyExistsError`, the same `Write*` errors, `FeatureInput`, `CreateFeatureResult`, `LeafletDocument` |
| `@hypercerts-org/sdk/organization` | `createOrganization`, `OrganizationAlreadyExistsError`, `RecordAlreadyExistsError`, the same `Write*` errors, `OrganizationInput`, `CreateOrganizationInput`, `CreateOrganizationResult`, `LeafletDocument` |
| `@hypercerts-org/sdk/context` | `createAttachment`, `createMeasurement`, `createEvaluation`, `createAcknowledgement`, `RecordAlreadyExistsError`, the same `Write*` errors, input/result types |
| `@hypercerts-org/sdk/blob` | `uploadBlob` |
| `@hypercerts-org/sdk/collection` | `createCollection`, `createActivityInCollection`, `RecordAlreadyExistsError`, `WriteError`, `WriteRejectedError`, `WriteOutcomeUnknownError`, `WriteResultMismatchError`, input/result types |

Expand All @@ -69,16 +70,18 @@ Operations are grouped by domain, each under its own subpath. Read the domain's
| Feature (`org.hypercerts.entity.feature`, with its tags and locations) | `@hypercerts-org/sdk/feature` | [references/feature.md](references/feature.md) |
| Collection (create a Collection with items; add a new Activity to an existing Collection) | `@hypercerts-org/sdk/collection` | [references/collection.md](references/collection.md) |
| Organization (`app.certified.actor.organization`, with its profile and locations) | `@hypercerts-org/sdk/organization` | [references/organization.md](references/organization.md) |
| Context (attachments, measurements, evaluations, acknowledgements) | `@hypercerts-org/sdk/context` | [references/context.md](references/context.md) |

Three things to know before opening a reference:
Things to know before opening a reference:

- `createProfile` needs an OAuth scope with both `create` and `update` on `app.certified.actor.profile`. With only `create` it fails with `WriteRejectedError` (403).
- `location: { uri }` inside a location is a link to external data; a whole location given as `{ uri }` in `createActivity` reuses an existing record.
- `createOrganization` takes the name, avatar, banner and website in `profileIfMissing`, not in `organization`, and an existing location as `{ uri }`, never a bare string.
- `createAttachment`, `createMeasurement`, `createEvaluation` and `createAcknowledgement` take a subject as `{ uri }`, never a bare string, and a measured value or score as a decimal string, never a number.

## 5. Images and files

- `create*` operations upload `Blob`/`File` values for you (`image`, `attachment`, a profile's `avatar` and `banner`, a location's `{ blob }`). Pass the file, not an upload result.
- `create*` operations upload `Blob`/`File` values for you (`image`, a rights record's `attachment`, `content` of `createAttachment` and `createEvaluation`, a profile's `avatar` and `banner`, a location's `{ blob }`). Pass the file, not an upload result.
- A string is stored as a URL and never fetched.
- Use `uploadBlob` only when writing a record yourself with the client:

Expand Down Expand Up @@ -107,7 +110,7 @@ Uploads happen before the write and are not rolled back, so a call that throws c

Order of work: validate input → read `{ uri }` records → upload blobs → validate against lexicons → one write. The SDK never retries.

The three write errors are exported from `@hypercerts-org/sdk/activity`, `/actor`, `/location`, `/tag`, `/feature`, `/collection` and `/organization` and extend `WriteError`. Every `WriteError` has `attempted`: the URI and CID of every record in the request, in request order: for `createActivity` the Activity is last; for `createActivityInCollection` the Collection is last and the Activity is just before it; for `createCollection` the Collection is last, after the records it points at; for `createOrganization` the organization is last. `instanceof WriteError` catches all three.
The three write errors are exported from `@hypercerts-org/sdk/activity`, `/actor`, `/location`, `/tag`, `/feature`, `/collection`, `/context` and `/organization` and extend `WriteError`. Every `WriteError` has `attempted`: the URI and CID of every record in the request, in request order: for `createActivity` the Activity is last; for `createActivityInCollection` the Collection is last and the Activity is just before it; for `createCollection` the Collection is last, after the records it points at; for `createOrganization` the organization is last. `instanceof WriteError` catches all three.

| Error | Meaning | What to do |
| -------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------- |
Expand Down Expand Up @@ -188,6 +191,6 @@ try {

## Verify

1. Imports come only from `@hypercerts-org/sdk`, `.../activity`, `.../actor`, `.../collection`, `.../feature`, `.../location`, `.../organization`, `.../tag` or `.../blob`.
1. Imports come only from `@hypercerts-org/sdk`, `.../activity`, `.../actor`, `.../collection`, `.../context`, `.../feature`, `.../location`, `.../organization`, `.../tag` or `.../blob`.
2. `tsc --noEmit` passes. The input types catch wrong field names and shapes.
3. `com.atproto.repo.getRecord` on each returned `uri` returns the record, and any references it holds match the URIs and CIDs the SDK returned.
152 changes: 152 additions & 0 deletions .agents/skills/hypercerts-org-sdk/references/context.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
# Context domain (`@hypercerts-org/sdk/context`)

Read [../SKILL.md](../SKILL.md) first for setup, blob uploads and error handling. Every example assumes `context` from `createSDKContext`.

| Function | Creates | Returns (`created: true` and a field only when the input had it) |
| ----------------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| `createAttachment` | `org.hypercerts.context.attachment` | `{ uri, cid, created, subjects?, location?, tags? }` |
| `createMeasurement` | `org.hypercerts.context.measurement` | `{ uri, cid, created, subjects?, locations? }` |
| `createEvaluation` | `org.hypercerts.context.evaluation` | `{ uri, cid, created, subject?, measurements?, location? }` |
| `createAcknowledgement` | `org.hypercerts.context.acknowledgement` | `{ uri, cid, created, subject, context? }` |

Each reference in the result is `{ uri, cid, created }`: `created: false` for an existing `{ uri }` record, with the CID it was pinned at.

All four write a TID-keyed record to the signed-in account's repo. The first three also create the new locations, tags and measurements they are given, in the **same** `applyWrites` as the record (all of it exists afterwards, or none); with nothing new to create, the call is a write of one record. For the location and tag fields see [location.md](location.md) and [tag.md](tag.md).

## Linking to records

| Input | Meaning |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `{ uri }` in `subjects`, `subject` | An existing record of **any** type. Read for its CID, stored as a strong reference, never modified. |
| `{ uri }` in `location`, `locations`, `tags`, `measurements` | An existing record of that field's type (`app.certified.location`, `org.hypercerts.vocab.tag`, `org.hypercerts.context.measurement`). Another type throws `TypeError`. |
| The fields of a record, in those same four | A new record, created in the same write. Never mixed with `uri`. |
| A string in `content`, an acknowledgement's `context` | A URL/URI stored as it is, never fetched, no CID. |
| A `Blob`/`File` in `content` | Uploaded for you (any type, up to 10 MB; a `Blob` needs a `type`). |

A subject is not limited to an Activity and is not changed: it does not learn about the attachment, measurement or evaluation, and nothing here links an existing record to its subject afterwards. Subject URIs must use a DID, not a handle. A bare string where `{ uri }` is required throws `TypeError`.

## createAttachment

```ts
import { createAttachment } from "@hypercerts-org/sdk/context";

const attachment = await createAttachment(context, {
title: "Field survey, June 2026",
contentType: "evidence", // update | report | audit | evidence | testimonial | methodology, others allowed
subjects: [{ uri: "at://did:plc:abc123/org.hypercerts.claim.activity/3k2a4b5c6d7e8" }],
content: [reportFile, "https://example.org/survey/2026-06"], // uploaded, stored as a URL
tags: [
{ category: "evidence-kind", key: "survey", name: "Survey", status: "accepted" }, // new
{ uri: "at://did:plc:abc123/org.hypercerts.vocab.tag/land-cover.wetland" }, // existing
],
location: { lpVersion: "1.0", srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84", locationType: "coordinate-decimal", location: { string: "90.17,27.47" } },
capturedAt: "2026-06-12T09:30:00+06:00",
});
attachment.tags?.[0]; // { uri, cid, created: true }
```

- `subjects` is optional: omit it for an attachment recorded before the claim it supports.
- `description` is a string (stored as `descriptionString`). Leaflet documents and `{ uri }` descriptions are not supported.
- A new tag's key is `<category>.<key>`; the SDK reads it first and a taken key throws `RecordAlreadyExistsError` with nothing written. Pass `{ uri }` to reuse a tag.

## createMeasurement

```ts
import { createMeasurement } from "@hypercerts-org/sdk/context";

const measurement = await createMeasurement(context, {
metric: "Forest area restored",
unit: "hectares",
value: "1234.56", // a decimal string, never a number
subjects: [{ uri: "at://did:plc:abc123/org.hypercerts.claim.activity/3k2a4b5c6d7e8" }],
startDate: "2026-01-01T00:00:00.000Z",
endDate: "2026-06-30T00:00:00.000Z",
measurers: ["did:plc:abc123"],
locations: [{ uri: "at://did:plc:abc123/app.certified.location/3k2a4b5c6d7e8" }], // or new location data
});
measurement.locations?.[0]; // { uri, cid, created: false }
```

- `value` must be a decimal string: `"1234.56"`, `"-3"`, `"0.10"`. A JavaScript number, `"1,234"` and `"1e3"` throw `TypeError`. The string is stored exactly as written.
- `measurers` (and an evaluation's `evaluators`) are DIDs stored as declared data: no proof the account took part or consents, nobody is notified.
- `endDate` before `startDate` throws. `methodURI` and `evidenceURI` entries are URIs, stored and never fetched.

## createEvaluation

```ts
import { createEvaluation } from "@hypercerts-org/sdk/context";

const evaluation = await createEvaluation(context, {
evaluators: ["did:plc:abc123"], // required, not defaulted to the signed-in account
summary: "The restoration meets its stated targets.",
subject: { uri: "at://did:plc:abc123/org.hypercerts.claim.activity/3k2a4b5c6d7e8" },
score: { min: "0", max: "5", value: "4.2" },
measurements: [
{ metric: "Forest area restored", unit: "hectares", value: "1234.56" }, // new, same fields as createMeasurement
{ uri: "at://did:plc:abc123/org.hypercerts.context.measurement/3k2a4b5c6d7e8" }, // existing
],
});
evaluation.measurements; // [{ uri, cid, created: true }, { uri, cid, created: false }]
```

- A new measurement may bring its own new `locations`, created in the same write and reported under `evaluation.measurements[i].locations`. A new measurement's `subjects` are not filled in from the evaluation's `subject`.
- `score` values are decimal strings and are compared exactly: `value` must be from `min` to `max` inclusive, or the call throws.
- `content` and `location` work as in `createAttachment`.

## createAcknowledgement

```ts
import { createAcknowledgement } from "@hypercerts-org/sdk/context";

await createAcknowledgement(context, {
subject: { uri: "at://did:plc:abc123/org.hypercerts.claim.contributorInformation/3k2a4b5c6d7e8" },
context: { uri: "at://did:plc:abc123/org.hypercerts.claim.activity/3k2a4b5c6d7e9" }, // pinned by CID
acknowledged: true, // false records a rejection
comment: "Happy to be listed.",
});
```

- Always written to the **signed-in** account's repo; there is no way to write one for another account. The SDK does not check the account's relationship to the subject.
- `context` is optional: a string is stored as a URI with no CID (lightweight); `{ uri }` is stored as a strong reference pinned to the CID read before the write. Use `{ uri }` when the version matters.
- No `location` or `tags`. Acknowledging the same subject twice creates two records.

## Fields

| Field | Used by | Type | Notes |
| - | - | - | - |
| `title` | attachment | `string` | Required, ≤ 256. |
| `subjects` | attachment, measurement | `{ uri }[]` | ≤ 100, any record type. |
| `contentType` | attachment | `string` | ≤ 64. |
| `content` | attachment, evaluation | `(Blob \| string)[]` | ≤ 100. Files uploaded, strings are URLs. |
| `shortDescription`, `description`, `langs` | attachment | `string`, `string`, `string[]` | `description` is a plain string only. |
| `location` | attachment, evaluation | new location or `{ uri }` | |
| `tags` | attachment | new vocabulary tags or `{ uri }`, ≤ 20 | |
| `capturedAt` | attachment | ISO 8601 with timezone | Not `createdAt`; omit if unknown. |
| `metric`, `unit`, `value` | measurement | `string` | All required; `value` is a decimal string. |
| `startDate`, `endDate` | measurement | ISO 8601 | `endDate` not before `startDate`. |
| `locations` | measurement | new locations or `{ uri }`, ≤ 100 | |
| `methodType`, `methodURI`, `evidenceURI`, `measurers`, `comment` | measurement | `string`, `string`, `string[]`, DID `string[]`, `string` | |
| `evaluators` | evaluation | DID `string[]` | Required, ≤ 1000. |
| `summary` | evaluation | `string` | Required, ≤ 5000. |
| `subject` | evaluation, acknowledgement | `{ uri }` | Required for an acknowledgement. |
| `measurements` | evaluation | new measurements or `{ uri }` | ≤ 100. |
| `score` | evaluation | `{ min, max, value }` decimal strings | |
| `acknowledged` | acknowledgement | `boolean` | Required. |
| `context`, `comment` | acknowledgement | `string \| { uri }`, `string` | |
| `createdAt` | all | ISO 8601 | Defaults to the time of the call. Nested new records get the call's time. |

Not supported: `signatures`, `shortDescriptionFacets`, `commentFacets`, and a non-string attachment `description`.

## Failures

Input errors, unresolved or wrongly typed `{ uri }` records and files the lexicon would reject fail before anything is sent. See [Handle failures](../SKILL.md#6-handle-failures) for the write errors. After `WriteOutcomeUnknownError` the primary record is last in `attempted`, and calling again would create new records under new keys: check the URIs first.

Files (`content`, a new tag's `referenceDocument`, a new location's `{ blob }`) are uploaded before the write and are not rolled back if it fails; see [Uploads are not part of the atomic write](../SKILL.md#uploads-are-not-part-of-the-atomic-write).

## Pitfalls

- `subjects: ["at://..."]` and `subject: "at://..."` throw. Wrap it: `{ uri: "at://..." }`.
- `value: 5` and `score: { value: 3 }` throw. Pass strings.
- A new measurement inside `createEvaluation` is created every call; to attach an existing measurement pass `{ uri }`. A `{ uri }` of an Activity in `measurements` throws.
- An acknowledgement's `context` string is not read or pinned. Pass `{ uri }` to pin the version.
- A `File` with no `type` cannot be uploaded: wrap it, `new Blob([file], { type: "application/pdf" })`.
9 changes: 9 additions & 0 deletions .changeset/context-records.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
"@hypercerts-org/sdk": minor
---

- Add `createAttachment`, `createMeasurement`, `createEvaluation` and `createAcknowledgement` at `@hypercerts-org/sdk/context`.
- Attachments and evaluations upload `Blob` content for you; subjects are `{ uri }` of any existing record and are never modified.
- Locations, vocabulary tags and measurements are new data or `{ uri }`, and are created in the same `applyWrites` as the record that points at them.
- Measured values and scores are decimal strings; a JavaScript number throws instead of being converted.
- Acknowledgements are always written to the signed-in account's repo.
4 changes: 4 additions & 0 deletions packages/sdk/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@
"types": "./dist/collection/index.d.ts",
"default": "./dist/collection/index.js"
},
"./context": {
"types": "./dist/context-records/index.d.ts",
"default": "./dist/context-records/index.js"
},
"./feature": {
"types": "./dist/feature/index.d.ts",
"default": "./dist/feature/index.js"
Expand Down
Loading
Loading