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
11 changes: 7 additions & 4 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: "5"
version: "6"
---

# @hypercerts-org/sdk
Expand Down Expand Up @@ -63,6 +63,7 @@ export const context = createSDKContext({
| `@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/social` | `followAccount`, `followEntity`, `like`, `repost`, `unfollowAccount`, `unfollowEntity`, `unlike`, `unrepost`, the `Write*` errors and input types |
| `@hypercerts-org/sdk/badge` | `createBadgeDefinition`, `awardBadge`, `respondToBadgeAward`, 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 @@ -82,13 +83,15 @@ Operations are grouped by domain, each under its own subpath. Read the domain's
| 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) |
| Social (follow accounts and records, like, repost, and undo them) | `@hypercerts-org/sdk/social` | [references/social.md](references/social.md) |
| Badge (`app.certified.badge.*`: definitions, awards to an account or record, responses) | `@hypercerts-org/sdk/badge` | [references/badge.md](references/badge.md) |

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.
- Social create functions take the **target**: `{ targetDid }` for an account, `{ targetUri }` (a full record URI) for a record. Undo functions (`unlike`, `unrepost`, `unfollowAccount`, `unfollowEntity`) take the **URI of your own like, repost or follow record** (`likeUri`, `repostUri`, `followUri`), not the target's, and return `void`. Keep the `uri` the create function returned.
- `awardBadge` takes `{ did }` or `{ uri }` as the subject and `{ uri }` or new fields as the definition; never build strong references or DID objects. `respondToBadgeAward` works only as the award's recipient.

## 5. Images and files

Expand Down Expand Up @@ -121,7 +124,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`, `/organization` and `/social` and extend `WriteError`. Every `WriteError` has `attempted`: the URI and CID of every record in the request, in request order (an undo function called without `cid` has an empty `attempted`; its message names the URI): 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`, `/badge`, `/location`, `/tag`, `/feature`, `/collection`, `/organization` and `/social` and extend `WriteError`. Every `WriteError` has `attempted`: the URI and CID of every record in the request, in request order (an undo function called without `cid` has an empty `attempted`; its message names the URI): 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 `awardBadge` the award is last, after a new definition; for `createOrganization` the organization is last. `instanceof WriteError` catches all three.

| Error | Meaning | What to do |
| -------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------- |
Expand Down Expand Up @@ -194,7 +197,7 @@ try {
- `createSDKContext({ client: session })` or passing an `@atproto/api` `Agent` throws. Wrap it: `new Client(session)`.
- `didResolver: oauthClient` throws. Pass `oauthClient.identityResolver`.
- Passing an `uploadBlob` result as `image` throws. Pass the `Blob`/`File`.
- Retrying blindly after `WriteOutcomeUnknownError` duplicates every record under new keys. The exception is a call whose records all have a fixed key and are only created if absent: `createProfile` and `createVocabularyTag`. `createOrganization` is also safe to repeat: the organization exists at most once, so a second call creates it or throws `OrganizationAlreadyExistsError`. Undo functions are safe to repeat too. `createFeature`, `createCollection`, `createWorkScopeTag`, `followAccount`, `followEntity`, `like` and `repost` are not safe to repeat.
- Retrying blindly after `WriteOutcomeUnknownError` duplicates every record under new keys. The exception is a call whose records all have a fixed key and are only created if absent: `createProfile` and `createVocabularyTag`. `createOrganization` is also safe to repeat: the organization exists at most once, so a second call creates it or throws `OrganizationAlreadyExistsError`. Undo functions are safe to repeat too. `createFeature`, `createCollection`, `createWorkScopeTag`, `createBadgeDefinition`, `awardBadge`, `respondToBadgeAward`, `followAccount`, `followEntity`, `like` and `repost` are not safe to repeat.
- An item of `createCollection` is `{ activity }`, `{ feature }`, `{ collection }` or `{ uri }`, never a bare Activity input; `{ uri }` must be an Activity, Feature or Collection.
- A vocabulary tag's key is `<category>.<key>` exactly as you pass it. A dot in either part throws a `TypeError`; the SDK does not normalise the parts.
- A work-scope tag URI is not a vocabulary tag URI: each field accepts one collection, and a `{ uri }` of another throws a `TypeError`.
Expand All @@ -204,6 +207,6 @@ try {

## Verify

1. Imports come only from `@hypercerts-org/sdk`, `.../activity`, `.../actor`, `.../collection`, `.../feature`, `.../location`, `.../organization`, `.../social`, `.../tag` or `.../blob`.
1. Imports come only from `@hypercerts-org/sdk`, `.../activity`, `.../actor`, `.../badge`, `.../collection`, `.../feature`, `.../location`, `.../organization`, `.../social`, `.../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.
104 changes: 104 additions & 0 deletions .agents/skills/hypercerts-org-sdk/references/badge.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# Badge domain (`@hypercerts-org/sdk/badge`)

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

Three operations that only create records: `createBadgeDefinition` (`app.certified.badge.definition`), `awardBadge` (`app.certified.badge.award`) and `respondToBadgeAward` (`app.certified.badge.response`). There is no operation that deletes, revokes or edits a definition, award or response.

## createBadgeDefinition

`createBadgeDefinition(context, input)` creates one definition in your repo and returns `{ uri, cid }`.

```ts
import { createBadgeDefinition } from "@hypercerts-org/sdk/badge";

const definition = await createBadgeDefinition(context, {
title: "Verified steward",
badgeType: "verification", // free text; values outside the lexicon's known set are fine
description: "Confirmed to manage the land they report on.",
icon: iconFile, // a PNG, JPEG, WebP or SVG File/Blob of at most 1 MiB, from your app, uploaded for you
allowedIssuers: ["did:plc:abc123"], // plain DIDs; the SDK stores them as DID objects
});
```

- `allowedIssuers`: omitted means **anyone** may award the badge; `[]` means **no one** may. You do not have to be on the list to create the definition, only to award it.
- `icon` is a `Blob`/`File`, not a URL and not an `uploadBlob` result. A type or size the lexicon refuses throws `TypeError` before anything is uploaded.
- Nothing is deduplicated: two calls create two definitions.

## awardBadge

`awardBadge(context, { definition, subject, note?, url?, validFrom?, validUntil?, createdAt? })` creates an award in your repo and returns `{ award, definition }`.

`definition` is either the fields of a **new** definition (created in the same commit) or `{ uri }` of an **existing** one (read, never rewritten):

```ts
import { awardBadge } from "@hypercerts-org/sdk/badge";

// An existing badge, awarded to an account.
const { award, definition } = await awardBadge(context, {
definition: { uri: "at://did:plc:abc123/app.certified.badge.definition/3k2a4b5c6d7e8" },
subject: { did: "did:plc:xyz789" },
note: "Completed the stewardship course.",
validUntil: "2027-06-01T00:00:00.000Z",
});
definition.created; // false

// A new badge awarded to a record (any type, any account's repository), one atomic commit.
await awardBadge(context, {
definition: { title: "Field verified", badgeType: "verification" },
subject: { uri: "at://did:plc:xyz789/org.hypercerts.claim.activity/3k2a4b5c6d7e8" },
});
```

- `subject` is `{ did }` (an account) or `{ uri }` (a record, identified by a DID, not a handle). You never build a strong reference or DID object: the SDK reads the record and pins its current CID.
- The award pins the definition by the CID it read. The signed-in account must be in **that version's** `allowedIssuers` (omitted: anyone, `[]`: no one), otherwise `Error` and nothing is written or uploaded.
- `validFrom` defaults to `createdAt` (which defaults to the time of the call). A `validUntil` earlier than `validFrom`, or than `createdAt` when `validFrom` is omitted, throws `TypeError`. Timestamps are stored as given. `validUntil` marks the award expired; it is not revocation.
- Awarding does not accept the badge for the recipient; they use `respondToBadgeAward`.
- The new definition and the award are one `applyWrites` commit: both exist afterwards, or neither does.
- After `WriteOutcomeUnknownError`, `attempted` lists the new definition (if any) first, then the award. Calling again is not safe: it would create a second award.
- Nothing is deduplicated: awarding the same badge to the same subject twice creates two awards.

## respondToBadgeAward

`respondToBadgeAward(context, { awardUri, response, weight?, createdAt? })` creates a response in **your** repo and returns `{ uri, cid }`. You must be the award's recipient.

```ts
import { respondToBadgeAward } from "@hypercerts-org/sdk/badge";

// The URI of the award, from the issuer or your app.
const awardUri = "at://did:plc:issuer/app.certified.badge.award/3k2a4b5c6d7e8";

await respondToBadgeAward(context, { awardUri, response: "accepted", weight: "2" });
// Or reject it (no weight here):
await respondToBadgeAward(context, { awardUri, response: "rejected" });
```

- The recipient of an award to an account is that account. For an award to a record it is the account whose repository holds the record (the SDK's rule; the lexicon does not say). Any other signed-in account, the issuer included, gets an `Error` and nothing is written.
- `weight` only goes with `"accepted"`; with `"rejected"` it throws `TypeError`. It must be a positive decimal number written as a string and is stored exactly as written (`"007.50"` stays `"007.50"`).
- Nothing is deduplicated or overwritten: every call creates a response under a new key. Responding twice leaves two responses. Calling again after `WriteOutcomeUnknownError` is not safe: it would create a second response.

## Uploads are outside the commit

A new definition's `icon` is the only file uploaded, before the write, and is 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). Invalid input, a refused issuer and an unreadable subject or definition fail before any upload; a rule of the award's or the new definition's lexicon (for example a `note` over 500 characters) is found only after it.

## Input fields

`BadgeDefinitionInput` (also `definition` of `awardBadge` when new):

| Field | Type | Notes |
| ---------------- | -------------------- | ---------------------------------------------------------------------- |
| `title` | `string` | Required. At most 256 characters. |
| `badgeType` | `string` | Required. At most 100 characters. Any value is accepted. |
| `description` | `string` | At most 500 graphemes. |
| `icon` | `Blob` / `File` | PNG, JPEG, WebP or SVG, at most 1 MiB. Uploaded by the SDK. |
| `allowedIssuers` | `string[]` (DIDs) | At most 100. Omitted: anyone. `[]`: no one. |
| `createdAt` | ISO 8601 `string` | Defaults to the time of the call. |

`AwardBadgeInput`: `definition` (`BadgeDefinitionInput` or `{ uri }`), `subject` (`{ did }` or `{ uri }`), `note` (at most 500 characters), `url`, `validFrom`, `validUntil`, `createdAt`.

`RespondToBadgeAwardInput`: `awardUri`, `response` (`"accepted"` or `"rejected"`), `weight` (accepted only, at most 50 characters), `createdAt`.

## Pitfalls

- `definition: { uri, title }` (a mix of an existing URI and new fields) throws `TypeError`. Pass one or the other.
- A definition `{ uri }` must be an `app.certified.badge.definition`; another type of record throws `TypeError`.
- An empty `allowedIssuers` is not "no restriction": it makes the badge impossible to award.
7 changes: 7 additions & 0 deletions .changeset/badges.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
"@hypercerts-org/sdk": minor
---

- Add `createBadgeDefinition`, `awardBadge` and `respondToBadgeAward` at `@hypercerts-org/sdk/badge`.
- `awardBadge` creates a new definition and the award in one `applyWrites` commit, or reuses an existing definition, and checks the signed-in account against its `allowedIssuers`.
- `respondToBadgeAward` only creates a response for the award's recipient: the account it is for, or the account whose repository holds the record it is for.
4 changes: 4 additions & 0 deletions packages/sdk/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@
"types": "./dist/actor/index.d.ts",
"default": "./dist/actor/index.js"
},
"./badge": {
"types": "./dist/badge/index.d.ts",
"default": "./dist/badge/index.js"
},
"./blob": {
"types": "./dist/blob/index.d.ts",
"default": "./dist/blob/index.js"
Expand Down
Loading
Loading