diff --git a/.agents/skills/hypercerts-org-sdk/SKILL.md b/.agents/skills/hypercerts-org-sdk/SKILL.md index e86e026..5887879 100644 --- a/.agents/skills/hypercerts-org-sdk/SKILL.md +++ b/.agents/skills/hypercerts-org-sdk/SKILL.md @@ -1,6 +1,6 @@ --- name: hypercerts-org-sdk -description: Write Hypercerts records from an app with @hypercerts-org/sdk. Covers setting up the SDK context from an authenticated @atproto/lex Client, creating an Activity (hypercert claim) together with its rights, locations, contributors and contributions in one atomic write, reusing existing records by URI, creating supporting records, standalone locations and an account profile on their own, structured CEL work scopes, vocabulary tags and work-scope tags, Features (zones and strata) with their tags and locations, adding a new Activity to an existing Collection (createActivityInCollection), uploading images and files as blobs, and handling write failures without creating duplicates. Use when app code imports @hypercerts-org/sdk, or the user wants to create a hypercert, activity claim, contributor, contribution, rights, location, vocabulary tag, work-scope tag, feature or CEL work scope record on a PDS, or to add an activity to a collection. Not for changing the SDK's own source. +description: Write Hypercerts records from an app with @hypercerts-org/sdk. Covers setting up the SDK context from an authenticated @atproto/lex Client, creating an Activity (hypercert claim) with its rights, locations, contributors and contributions in one atomic write, reusing existing records by URI, standalone supporting records, locations and account profiles, structured CEL work scopes, vocabulary and work-scope tags, Features (zones and strata), adding an Activity to an existing Collection (createActivityInCollection), organizations with their profile and locations (createOrganization), uploading images and files as blobs, and handling write failures without creating duplicates. Use when app code imports @hypercerts-org/sdk, or the user wants to create a hypercert, activity claim, contributor, contribution, rights, location, vocabulary tag, work-scope tag, feature, organization or CEL work scope record on a PDS, or to add an activity to a collection. Not for changing the SDK's own source. metadata: author: hypercerts-org version: "3" @@ -50,6 +50,7 @@ Make a new context when the signed-in account changes. Records are always writte | `@hypercerts-org/sdk/location` | `createLocation`, the same `Write*` errors, `LocationInput`, `LocationValue` | | `@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/blob` | `uploadBlob` | | `@hypercerts-org/sdk/collection` | `createActivityInCollection`, `WriteError`, `WriteRejectedError`, `WriteOutcomeUnknownError`, `WriteResultMismatchError`, input/result types | @@ -67,11 +68,13 @@ Operations are grouped by domain, each under its own subpath. Read the domain's | Tag (`org.hypercerts.vocab.tag`, `org.hypercerts.workscope.tag`) | `@hypercerts-org/sdk/tag` | [references/tag.md](references/tag.md) | | Feature (`org.hypercerts.entity.feature`, with its tags and locations) | `@hypercerts-org/sdk/feature` | [references/feature.md](references/feature.md) | | Collection (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) | -Two things to know before opening a reference: +Three 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. ## 5. Images and files @@ -104,13 +107,13 @@ 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` and `/collection` 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. `instanceof WriteError` catches all three. +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 `createOrganization` the organization is last. `instanceof WriteError` catches all three. | Error | Meaning | What to do | | -------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------- | | `TypeError` | Bad input. The message names the field (e.g. `contributors[1].weight`). Nothing written. | Fix the input. | | `Error` | Not authenticated, a `{ uri }` record could not be read, or an upload failed. Nothing written. | Fix auth or the URI, then retry. | -| `WriteRejectedError` | PDS answered 4xx. Nothing created or changed. `status`, `code`. | Safe to fix and retry. `InvalidSwap` (collection writes): the account was written to after it was read; call again. | +| `WriteRejectedError` | PDS answered 4xx. Nothing created or changed. `status`, `code`. | Safe to fix and retry. `InvalidSwap`: see [Concurrent changes](#concurrent-changes-invalidswap). | | `RecordAlreadyExistsError` | A key you chose is taken (a `WriteRejectedError`). `uri` names the record. Nothing written. | Use it as `{ uri }`, or choose another key. | | `WriteOutcomeUnknownError` | Network error, timeout or 5xx. The records may exist. `attempted` lists every URI. | Check before retrying. | | `WriteResultMismatchError` | Created, but the PDS reported other URIs/CIDs (`reported` vs `attempted`). | Do not retry. Log it and inspect the records. | @@ -143,11 +146,40 @@ try { `recordExists` is your own helper around `com.atproto.repo.getRecord`, which returns `RecordNotFound` when the record is missing. +### Concurrent changes (`InvalidSwap`) + +`applyWrites` cannot say "only if this record is absent" or "only if it is unchanged". `createOrganization` and `createActivityInCollection` decide something from what they read, so they read the account's latest commit first, then the records, and send the write conditional on that commit. If **anything** wrote to the account in between (even an unrelated record, such as a post), the PDS refuses the whole request: `WriteRejectedError` with `code === "InvalidSwap"`. Nothing was written and nothing is wrong with the input. The SDK never retries or merges. Calling again reads everything afresh, so it is safe. + +A taken key has the same `code`, but calling again cannot fix it. `RecordAlreadyExistsError` (and its subclasses `OrganizationAlreadyExistsError` and `ProfileAlreadyExistsError`) is a `WriteRejectedError` too, so rule it out first: + +```ts +import { + createOrganization, + RecordAlreadyExistsError, + WriteRejectedError, +} from "@hypercerts-org/sdk/organization"; + +try { + return await createOrganization(context, input); +} catch (error) { + if ( + error instanceof WriteRejectedError && + error.code === "InvalidSwap" && + !(error instanceof RecordAlreadyExistsError) + ) { + return await createOrganization(context, input); // reads everything afresh + } + throw error; +} +``` + +`createActivityInCollection` uses the same check, with `WriteRejectedError` from `@hypercerts-org/sdk/collection`. Calling again does not help when the cause is a taken `key` of a new tag in its `activity`: pass `{ uri }` or choose another key. + ## Pitfalls - `createSDKContext({ client: session })` or passing an `@atproto/api` `Agent` throws. Wrap it: `new Client(session)`. - 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`. `createFeature` and `createWorkScopeTag` 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`. `createFeature` and `createWorkScopeTag` are not safe to repeat. - A vocabulary tag's key is `.` 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`. - One write holds at most 200 records on the reference PDS. A larger call throws a `TypeError` before anything is written; the SDK does not split it. Create some records first and pass their URIs. @@ -155,6 +187,6 @@ try { ## Verify -1. Imports come only from `@hypercerts-org/sdk`, `.../activity`, `.../actor`, `.../collection`, `.../feature`, `.../location`, `.../tag` or `.../blob`. +1. Imports come only from `@hypercerts-org/sdk`, `.../activity`, `.../actor`, `.../collection`, `.../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. diff --git a/.agents/skills/hypercerts-org-sdk/references/collection.md b/.agents/skills/hypercerts-org-sdk/references/collection.md index 2763ecc..a415008 100644 --- a/.agents/skills/hypercerts-org-sdk/references/collection.md +++ b/.agents/skills/hypercerts-org-sdk/references/collection.md @@ -29,20 +29,7 @@ const { activity, collection } = await createActivityInCollection(context, { ## Concurrent writes (`InvalidSwap`) -`applyWrites` cannot guard a single record, so the SDK reads the repository's latest commit, then the Collection, and sends the write conditional on that commit. If **anything** wrote to the account in between (even an unrelated record), the PDS refuses the whole request: `WriteRejectedError` with `code === "InvalidSwap"`. Nothing was written, so calling again is safe. The SDK never retries or merges. - -```ts -import { createActivityInCollection, WriteRejectedError } from "@hypercerts-org/sdk/collection"; - -try { - return await createActivityInCollection(context, input); -} catch (error) { - if (error instanceof WriteRejectedError && error.code === "InvalidSwap") { - return await createActivityInCollection(context, input); // reads the Collection afresh - } - throw error; -} -``` +The write is conditional on the account not having changed since the Collection was read, so a concurrent change to its `items` cannot be overwritten with a stale list. When it did change you get `WriteRejectedError` with `code === "InvalidSwap"`: see [Concurrent changes](../SKILL.md#concurrent-changes-invalidswap) for the rule and the retry example. Any other `WriteRejectedError` (4xx) is not fixed by calling again. After `WriteOutcomeUnknownError`, `attempted` lists the new records and, last, the Collection: check the Activity and whether the Collection lists it before retrying, or you create a second Activity. diff --git a/.agents/skills/hypercerts-org-sdk/references/organization.md b/.agents/skills/hypercerts-org-sdk/references/organization.md new file mode 100644 index 0000000..c471799 --- /dev/null +++ b/.agents/skills/hypercerts-org-sdk/references/organization.md @@ -0,0 +1,107 @@ +# Organization domain (`@hypercerts-org/sdk/organization`) + +Read [../SKILL.md](../SKILL.md) first for setup, blob uploads and error handling. Every example assumes `context` from `createSDKContext`. + +`createOrganization(context, { organization, profileIfMissing? })` creates the signed-in account's organization record (`app.certified.actor.organization`, key `self`) and, if the account has no profile yet, its profile (`app.certified.actor.profile`, see [profile.md](profile.md)), together with any new locations (see [location.md](location.md)), in one `applyWrites` commit. It creates records in the account you are signed in as; it does not create accounts. + +```ts +import { createOrganization } from "@hypercerts-org/sdk/organization"; + +// `logoFile` is a File, for example from an . +const { organization, profile, location, additionalLocations } = await createOrganization(context, { + organization: { + legalName: "Phobjikha Conservation Society", + organizationType: ["ngo"], + urls: [{ url: "https://example.org/donate", label: "Donate" }], + logo: logoFile, // uploaded; a URL string is stored as it is, never fetched + longDescription: "We plant native trees in the Phobjikha valley.", + location: { + lpVersion: "1.0", + srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84", + locationType: "country-code", + location: { string: "BT" }, + }, // new + additionalLocations: [ + { uri: "at://did:plc:abc123/app.certified.location/3k2a4b5c6d7e8" }, // existing, reused + ], + }, + // Used only when the account has no profile. Ignored (and its images not uploaded) otherwise. + profileIfMissing: { displayName: "Phobjikha Conservation", avatar: avatarFile }, +}); +organization; // { uri, cid } +profile; // { uri, cid, created: true } (false when the account already had one) +location; // { uri, cid, created: true } +additionalLocations; // [{ uri, cid, created: false }] +``` + +## The profile + +The display name, short description, website, avatar and banner belong to the **profile**, not the organization. Put them in `profileIfMissing`. The organization record holds only organization fields (legal name, logo, public email, types, URLs, locations, founding date, long description, languages, visibility). + +| Account state | What happens | +| --------------------------------------- | --------------------------------------------------------------------------------------------- | +| Has a profile | Reused exactly as it is: `created: false`. `profileIfMissing` is **not** an update and its images are not uploaded. It is still validated, so a typo in it throws either way. | +| No profile, `profileIfMissing` given | Created in the same commit: `created: true`. | +| No profile, no `profileIfMissing` | `TypeError` naming `profileIfMissing`. Nothing is uploaded or written. The SDK never creates an empty profile. | + +There is no operation that updates a profile or an organization. + +## The organization may already exist + +```ts +import { createOrganization, OrganizationAlreadyExistsError } from "@hypercerts-org/sdk/organization"; + +try { + await createOrganization(context, input); +} catch (error) { + if (!(error instanceof OrganizationAlreadyExistsError)) throw error; + // Nothing was uploaded or written. `error.uri` is the existing record; the SDK cannot update it. +} +``` + +`OrganizationAlreadyExistsError` extends `RecordAlreadyExistsError`, which extends `WriteRejectedError` (`status` 400, `code` `"InvalidSwap"`), so check for it first. It is thrown before any upload. + +A failed read of the profile or the organization (network error, 5xx, 403) throws an `Error`. It is never taken as "absent". + +## Locations and the long description + +- `location` (primary) and each entry of `additionalLocations` are either the fields of a **new** location or `{ uri }` of an **existing** `app.certified.location`, which is read and reused unchanged. A bare string such as `location: "at://…"` throws `TypeError`; write `{ uri: "at://…" }`. +- Order is kept, the primary location stays separate from the additional ones, and nothing is deduplicated: the SDK does not notice the primary location repeated in `additionalLocations`. +- `longDescription` is a string (stored inline as plain text or Markdown), a Leaflet document (it needs `$type: "pub.leaflet.pages.linearDocument"`, stored inline as it is), or `{ uri }` of an existing record of any type (stored as a strong reference with the CID read first). The SDK never creates a document record. The result's `longDescription` carries the pinned reference only for `{ uri }`. + +## Concurrent writes (`InvalidSwap`) + +The write is conditional on the account not having changed since the profile and the organization were read, so another call creating either one in between cannot make "reuse or create the profile" stale. When it did change you get `WriteRejectedError` with `code === "InvalidSwap"`: see [Concurrent changes](../SKILL.md#concurrent-changes-invalidswap) for the rule and the retry example. Calling again reads everything afresh and then throws `OrganizationAlreadyExistsError` if the other writer created the organization. + +## After `WriteOutcomeUnknownError` + +`attempted` lists the profile (if it would be created), the new locations and, last, the organization. Calling `createOrganization` again is safe even though new locations get fresh record keys: it reads the organization first, so it either creates everything or throws `OrganizationAlreadyExistsError`, which means the first attempt succeeded (no second set of locations or profile). The new records are those of the first error's `attempted`. + +## Uploads are outside the commit + +A `Blob`/`File` logo, a new location's `{ blob }` and (when the profile is created) the profile's images are uploaded after the reads and 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). An invalid input, an existing organization, a missing profile without `profileIfMissing`, a failed read, an unreadable `{ uri }` or more than 200 new records fails before any upload. A lexicon rule that rejects a record (for example more than three `langs`) is only found after the uploads. + +## Pitfalls + +- The session needs `create` on `app.certified.actor.organization`, and on `app.certified.actor.profile` and `app.certified.location` when the call creates them. No `update` is needed. +- One write holds at most 200 records: the organization, a created profile and every new location. More is a `TypeError`; create some locations first and pass their `{ uri }`. +- An explicit `profileIfMissing: {}` is data: it creates a profile with only `createdAt`. + +## `OrganizationInput` (`app.certified.actor.organization`) + +Every field is optional. + +| Field | Type | Notes | +| --------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| `legalName` | `string` | Registered legal name. Max 256 graphemes. The public name is the profile's `displayName`. | +| `publicEmail` | `string` | Shown publicly. Max 254 characters. Never an internal address. | +| `organizationType` | `string[]` | For example `ngo`, `cooperative`. Max 10, each max 100 graphemes. | +| `urls` | `{ url: string; label?: string }[]` | Reference links. The main website is the profile's `website`. | +| `logo` | `Blob \| string` | JPEG/PNG/WebP up to 5 MB (uploaded), or a URL. The square symbol is the profile's `avatar`. | +| `location` | `LocationInput \| { uri }` | Primary location: new, or an existing one reused. | +| `additionalLocations` | `(LocationInput \| { uri })[]` | Max 1000 by the lexicon, but a write holds 200 records. Do not repeat the primary location. | +| `foundedDate` | `string` | ISO 8601 date-time; use midnight UTC. | +| `longDescription` | `string \| LeafletDocument \| { uri }` | See above. | +| `langs` | `string[]` | BCP-47 tags of the text, up to 3. | +| `visibility` | `string` | `public` or `unlisted`; other values are accepted. | +| `createdAt` | `string` | ISO 8601 date-time. Defaults to the time of the call. | diff --git a/.changeset/create-organization.md b/.changeset/create-organization.md new file mode 100644 index 0000000..6360e08 --- /dev/null +++ b/.changeset/create-organization.md @@ -0,0 +1,7 @@ +--- +"@hypercerts-org/sdk": minor +--- + +- Add `createOrganization` at `@hypercerts-org/sdk/organization`: creates the account's organization record, its profile if missing (`profileIfMissing`) and new locations in one atomic commit. +- An existing profile is reused unchanged (`profile.created` is `false`); an existing organization throws `OrganizationAlreadyExistsError`. Existing locations are passed as `{ uri }`. +- The commit is rejected with `WriteRejectedError` (`code` `"InvalidSwap"`) if the account was written to after the profile and organization were read; nothing is written. diff --git a/packages/sdk/package.json b/packages/sdk/package.json index c133990..e5c1ae2 100644 --- a/packages/sdk/package.json +++ b/packages/sdk/package.json @@ -39,6 +39,10 @@ "types": "./dist/location/index.d.ts", "default": "./dist/location/index.js" }, + "./organization": { + "types": "./dist/organization/index.d.ts", + "default": "./dist/organization/index.js" + }, "./tag": { "types": "./dist/tag/index.d.ts", "default": "./dist/tag/index.js" diff --git a/packages/sdk/src/actor/build-profile.ts b/packages/sdk/src/actor/build-profile.ts index 80aa085..042ea77 100644 --- a/packages/sdk/src/actor/build-profile.ts +++ b/packages/sdk/src/actor/build-profile.ts @@ -38,7 +38,7 @@ export interface ProfileInput { createdAt?: string | undefined; } -const profileKind: RecordKind = recordKind( +export const profileKind: RecordKind = recordKind( profile.main, { displayName: optionalText, diff --git a/packages/sdk/src/collection/create-activity-in-collection.ts b/packages/sdk/src/collection/create-activity-in-collection.ts index c60d63b..575db53 100644 --- a/packages/sdk/src/collection/create-activity-in-collection.ts +++ b/packages/sdk/src/collection/create-activity-in-collection.ts @@ -72,15 +72,10 @@ const inputSchema = strictObject({ * `createdAt` and the existing items with their order, weights and references. The existing items * are not read again or checked. The new item is appended at the end. * - * Concurrent changes: `applyWrites` cannot say "only if this record is unchanged", so the SDK - * reads the latest commit of the repository, then the Collection, and asks the PDS to apply the - * write only if the repository is still at that commit (`swapCommit`). If anything else wrote to - * the account in between, the PDS rejects the whole request, nothing is written, and this throws - * {@link WriteRejectedError} with `code` `"InvalidSwap"`. That guards against a lost update, but it - * is coarse: it also fires for an unrelated write to the same account (a post, a like, another - * call of this function), so an account that writes often will see it now and then. The window is - * short, because the uploads happen before the repository is read. The SDK does not retry or - * merge; call again and it reads the Collection afresh. + * Concurrent changes: the write is conditional on the account not having changed since the + * Collection was read, so a concurrent change to its `items` cannot be overwritten with a stale + * list. If it did change, this throws {@link WriteRejectedError} with `code` `"InvalidSwap"`; see + * there. * * Signatures: the Collection's `signatures` field is neither checked nor changed. Appending an * item changes the record's content, so any signature that was made over the previous content no diff --git a/packages/sdk/src/feature/build-feature.ts b/packages/sdk/src/feature/build-feature.ts index cd406c5..98a3747 100644 --- a/packages/sdk/src/feature/build-feature.ts +++ b/packages/sdk/src/feature/build-feature.ts @@ -1,16 +1,16 @@ import { l } from "@atproto/lex"; -import * as defs from "@hypercerts-org/lexicon/org/hypercerts/defs"; import * as feature from "@hypercerts-org/lexicon/org/hypercerts/entity/feature"; -import * as linearDocument from "@hypercerts-org/lexicon/pub/leaflet/pages/linearDocument"; import type { SDKContext } from "../context.js"; import { createRecordTree } from "../internal/create-record.js"; import { optionalText } from "../internal/input.js"; -import { type RecordKind, recordKind, references } from "../internal/record-kind.js"; import { - type ExistingRecord, - isExistingRecord, - type SupportingRecordRef, -} from "../internal/slots.js"; + type LeafletDocument, + longDescription, + longDescriptionReference, + longDescriptionTransform, +} from "../internal/long-description.js"; +import { type RecordKind, recordKind, references } from "../internal/record-kind.js"; +import type { ExistingRecord, SupportingRecordRef } from "../internal/slots.js"; import { type LocationInput, locationKind } from "../location/build-location.js"; import { type VocabularyTagInput, @@ -18,11 +18,7 @@ import { vocabularyTagKind, } from "../tag/build-tag.js"; -/** - * A Leaflet document (`pub.leaflet.pages.linearDocument`): rich text in blocks. Passed to the record - * as it is; the lexicon validates it. - */ -export type LeafletDocument = l.$Typed; +export type { LeafletDocument }; /** The data of a new `org.hypercerts.entity.feature` record. */ export interface FeatureInput { @@ -80,39 +76,21 @@ export interface CreateFeatureResult { locations: readonly SupportingRecordRef[]; } -const isLeafletDocument = (value: unknown): value is LeafletDocument => - typeof value === "object" && - value !== null && - "$type" in value && - value.$type === linearDocument.$type; - -const featureDescription = l.custom( - (value): value is string | LeafletDocument | ExistingRecord => - typeof value === "string" || isExistingRecord(value) || isLeafletDocument(value), - `must be a string, { uri } of an existing record, or a Leaflet document with $type "${linearDocument.$type}"`, -); - const featureKind: RecordKind = recordKind( feature.main, { type: optionalText, title: l.string(), - description: l.optional(featureDescription), + description: l.optional(longDescription), langs: l.optional(l.array(l.string())), sameAs: l.optional(l.array(l.string())), }, - { - // A reference arrives here already stored with its `$type` (see `typed` below). - description: (_build, _field, value: string | object) => - Promise.resolve(typeof value === "string" ? defs.descriptionString.build({ value }) : value), - }, + { description: longDescriptionTransform }, { references: { locations: references.many(() => locationKind), tags: references.many(() => vocabularyTagKind), - // Only `{ uri }` is a reference. The description's union has the strong reference as a member, - // so it is stored with its `$type`. - description: { kind: undefined, many: false, when: isExistingRecord, typed: true }, + description: longDescriptionReference, }, }, ); diff --git a/packages/sdk/src/internal/long-description.ts b/packages/sdk/src/internal/long-description.ts new file mode 100644 index 0000000..f5e1816 --- /dev/null +++ b/packages/sdk/src/internal/long-description.ts @@ -0,0 +1,52 @@ +import { l } from "@atproto/lex"; +import * as defs from "@hypercerts-org/lexicon/org/hypercerts/defs"; +import * as linearDocument from "@hypercerts-org/lexicon/pub/leaflet/pages/linearDocument"; +import type { FieldTransform, ReferenceField } from "./record-kind.js"; +import { type ExistingRecord, isExistingRecord } from "./slots.js"; + +/** + * A Leaflet document (`pub.leaflet.pages.linearDocument`): rich text in blocks. Passed to the record + * as it is; the lexicon validates it. + */ +export type LeafletDocument = l.$Typed; + +const isLeafletDocument = (value: unknown): value is LeafletDocument => + typeof value === "object" && + value !== null && + "$type" in value && + value.$type === linearDocument.$type; + +/** + * The input schema of a long description: a string, a Leaflet document with its `$type`, or `{ uri }` + * of an existing record. + * + * Internal. For lexicon fields that are the union of `org.hypercerts.defs#descriptionString`, + * `pub.leaflet.pages.linearDocument` and `com.atproto.repo.strongRef` (a Feature's `description`, an + * organization's `longDescription`). Use it with `longDescriptionTransform` and + * `longDescriptionReference`, which turn each of the three into the stored value. + */ +export const longDescription = l.custom( + (value): value is string | LeafletDocument | ExistingRecord => + typeof value === "string" || isExistingRecord(value) || isLeafletDocument(value), + `must be a string, { uri } of an existing record, or a Leaflet document with $type "${linearDocument.$type}"`, +); + +/** + * The `recordKind` transform of a long description: a string becomes `descriptionString`, and a + * Leaflet document is kept as it is. A reference arrives here already stored with its `$type` (see + * `longDescriptionReference`) and is kept too. + */ +export const longDescriptionTransform: FieldTransform = (_build, _field, value: string | object) => + Promise.resolve(typeof value === "string" ? defs.descriptionString.build({ value }) : value); + +/** + * The `recordKind` reference spec of a long description. Only `{ uri }` is a reference, to a record + * of any type. The field's union has the strong reference as a member, so it is stored with its + * `$type`. + */ +export const longDescriptionReference: ReferenceField = { + kind: undefined, + many: false, + when: isExistingRecord, + typed: true, +}; diff --git a/packages/sdk/src/internal/submit-writes.ts b/packages/sdk/src/internal/submit-writes.ts index 1d7d46b..153fead 100644 --- a/packages/sdk/src/internal/submit-writes.ts +++ b/packages/sdk/src/internal/submit-writes.ts @@ -28,9 +28,19 @@ export abstract class WriteError extends Error { * needs cleaning up, except any blobs uploaded before the write (see {@link uploadBlob}). * * `status` and `code` are the HTTP status and the XRPC error code (for example `InvalidRequest`). - * `code` is `InvalidSwap` when the repository changed after the SDK read it (see the operation's - * documentation): nothing is wrong with the input, and calling again reads the repository afresh. * `cause` is the client's original error. + * + * @remarks + * Concurrent changes (`InvalidSwap`): `applyWrites` cannot say "only if this record is absent" or + * "only if it is unchanged". An operation that decides something from what it read (whether a + * record exists, what a record holds) therefore reads the repository's latest commit first, then + * those records, and asks the PDS to apply the write only if the repository is still at that + * commit (`swapCommit`). If anything else wrote to the account in between, the PDS rejects the + * whole request with `code` `"InvalidSwap"` and nothing is written. The check is coarse: an + * unrelated write to the same account (a post, a like, another call) causes it too, so an account + * that writes often will see it now and then. Nothing is wrong with the input. The SDK does not + * retry or merge; call again, which reads everything afresh. {@link RecordAlreadyExistsError} has + * the same `code`, but calling again cannot fix a taken key: rule it out first. */ export class WriteRejectedError extends WriteError { override readonly name: string = "WriteRejectedError"; @@ -87,7 +97,9 @@ export class RecordAlreadyExistsError extends WriteRejectedError { * attempt had succeeded. The exception is a record whose key is fixed or decided by its data and * that is only created if absent (`createProfile`, and `createVocabularyTag`, whose nested tags are * checked before the write): calling again either creates it or is refused because it already - * exists, most likely from the first attempt, so it cannot duplicate. + * exists, most likely from the first attempt, so it cannot duplicate. `createOrganization` is + * another: it reads its organization, which has a fixed key, before every attempt, so calling again + * either creates everything or is refused because the organization already exists. */ export class WriteOutcomeUnknownError extends WriteError { override readonly name = "WriteOutcomeUnknownError"; @@ -124,11 +136,18 @@ export interface SubmitOptions { */ readonly swapCommit?: CidString; /** - * Whether calling again after an unknown outcome cannot duplicate records: every record has a key - * the input decided, and the caller checks none exists before sending. Only changes the advice in - * the error message. + * Whether calling again after an unknown outcome cannot duplicate records: either every record has + * a key the input decided and the caller checks none exists before sending, or the caller reads a + * record with a fixed key before every attempt, which a first attempt that succeeded would have + * created, and gives `retrySafeReason`. Only changes the advice in the error message. */ readonly retrySafe?: boolean; + /** + * With `retrySafe`, why calling again is safe when that is not "every record has a fixed key". It + * completes the sentence "calling again is safe: ...", so it must read as a clause + * without a final period. Absent: the message says every record has a fixed key. + */ + readonly retrySafeReason?: string; } /** What one request tried to write, for messages and for the errors' `attempted`. */ @@ -169,8 +188,8 @@ export function assertWithinWriteLimit(operation: string, count: number): void { * Internal. Boundaries: * - Never retries and never splits the request; the caller decides what to do about a failure. * `options.retrySafe` says whether calling again after an unknown outcome cannot duplicate records - * (every record has a key the input decided, and the caller checks none exists before sending); - * it only changes the advice in the error message. + * (see `SubmitOptions.retrySafe`, and `retrySafeReason` for the wording); it only changes the + * advice in the error message. * - Does not pass `validate`, so the PDS applies its own default; records are validated by the * builders against their lexicons before they get here. * - Classifies a failure as definite only when the PDS answered with an HTTP 4xx other than 408. @@ -224,6 +243,7 @@ export async function submitWrites( return response.body.results; }, options.retrySafe ?? false, + options.retrySafeReason, ); } @@ -301,12 +321,13 @@ async function submit( request: Request, send: () => Promise, retrySafe: boolean, + retrySafeReason?: string, ): Promise { let results: readonly unknown[] | undefined; try { results = await send(); } catch (error) { - throw classifyFailure(operation, error, request, retrySafe); + throw classifyFailure(operation, error, request, retrySafe, retrySafeReason); } assertReportedRefs(operation, request, results); } @@ -338,7 +359,13 @@ const newRecordsOf = (refs: readonly StrongRef[]) => const NOT_WRITTEN = { created: "not created", changed: "not changed" }; const MAYBE_WRITTEN = { created: "created", changed: "changed" }; -function classifyFailure(operation: string, error: unknown, request: Request, retrySafe: boolean) { +function classifyFailure( + operation: string, + error: unknown, + request: Request, + retrySafe: boolean, + retrySafeReason?: string, +) { const status = property(error, "status"); const code = property(error, "error"); const reason = describeError(error); @@ -354,18 +381,24 @@ function classifyFailure(operation: string, error: unknown, request: Request, re } return new WriteOutcomeUnknownError( `${operation}: no usable answer from the PDS (${reason}), so it is not known whether ${describeEffects(request, MAYBE_WRITTEN)}: ${attempted.map((ref) => ref.uri).join(", ")}. ` + - retryAdvice(operation, request, retrySafe), + retryAdvice(operation, request, retrySafe, retrySafeReason), attempted, { cause: error }, ); } -function retryAdvice(operation: string, request: Request, retrySafe: boolean): string { +function retryAdvice( + operation: string, + request: Request, + retrySafe: boolean, + retrySafeReason?: string, +): string { if (retrySafe) { const subject = - attemptedOf(request).length !== 1 + retrySafeReason ?? + (attemptedOf(request).length !== 1 ? "every record has a fixed key and none is created if it exists, so the call either creates them or fails because one already exists" - : "the record has a fixed key and is only created if absent, so the call either creates it or fails because it already exists"; + : "the record has a fixed key and is only created if absent, so the call either creates it or fails because it already exists"); return `The SDK does not retry, but calling ${operation} again is safe: ${subject}, most likely from the first attempt. To check first, use com.atproto.repo.getRecord.`; } const check = diff --git a/packages/sdk/src/organization/build-organization.ts b/packages/sdk/src/organization/build-organization.ts new file mode 100644 index 0000000..57c6699 --- /dev/null +++ b/packages/sdk/src/organization/build-organization.ts @@ -0,0 +1,104 @@ +import { l } from "@atproto/lex"; +import * as organization from "@hypercerts-org/lexicon/app/certified/actor/organization"; +import { optionalMedia, optionalText, strictObject } from "../internal/input.js"; +import { + type LeafletDocument, + longDescription, + longDescriptionReference, + longDescriptionTransform, +} from "../internal/long-description.js"; +import { mediaTransform } from "../internal/media.js"; +import { type RecordKind, recordKind, references } from "../internal/record-kind.js"; +import type { ExistingRecord } from "../internal/slots.js"; +import { type LocationInput, locationKind } from "../location/build-location.js"; + +/** A labeled URL of an organization. */ +export interface OrganizationUrl { + /** The URL. At most 2048 graphemes. */ + url: string; + /** A human-readable label, for example `Donation page`. At most 64 graphemes. */ + label?: string | undefined; +} + +/** + * The data of the `app.certified.actor.organization` record of an account. + * + * @remarks + * Only what belongs to the organization is here. The name, short description, website, avatar and + * banner belong to the account's profile: see `profileIfMissing` in {@link CreateOrganizationInput}. + */ +export interface OrganizationInput { + /** The organization's registered legal name. At most 256 graphemes. */ + legalName?: string | undefined; + /** A contact address to show publicly. Records are public, so never an internal one. At most 254 characters. */ + publicEmail?: string | undefined; + /** + * The organization's legal or operational structures, for example `nonprofit` or `cooperative`. At + * most 10, each at most 100 graphemes. + */ + organizationType?: readonly string[] | undefined; + /** + * Further reference links, each with an optional label: social media, a donation page. The main + * website belongs to the profile. + */ + urls?: readonly OrganizationUrl[] | undefined; + /** + * The full logo (a wordmark, or the symbol with the name): an image `Blob` or `File` (JPEG, PNG + * or WebP, up to 5 MB) that the SDK uploads, or a URL string that is stored as it is. The square + * symbol alone belongs to the profile's `avatar`. + */ + logo?: Blob | string | undefined; + /** + * The primary location, where the organization is based: the data of a new location, or `{ uri }` + * of an existing one, which is reused unchanged. + */ + location?: LocationInput | ExistingRecord | undefined; + /** + * Further locations, such as branches or field offices, at most 1000: each entry is the data of a + * new location or `{ uri }` of an existing one. Do not repeat the primary `location` here; the + * order is kept and nothing is deduplicated. + */ + additionalLocations?: readonly (LocationInput | ExistingRecord)[] | undefined; + /** + * When the organization was established, as an ISO 8601 date-time. Use midnight UTC, for example + * `2005-01-01T00:00:00.000Z`: only the date is meaningful. + */ + foundedDate?: string | undefined; + /** + * A long description: plain text or Markdown, a {@link LeafletDocument} stored inline, or `{ uri }` + * of an existing document record of any type, stored as a reference to it. The SDK never creates a + * document record. + */ + longDescription?: string | LeafletDocument | ExistingRecord | undefined; + /** Languages of the text fields as BCP-47 tags (up to three), for example `["en"]`. */ + langs?: readonly string[] | undefined; + /** Whether the organization may be listed: `public` or `unlisted`. Other values are accepted. */ + visibility?: string | undefined; + /** An ISO 8601 date-time. Defaults to the time of the call. */ + createdAt?: string | undefined; +} + +const urlItem = strictObject({ url: l.string(), label: optionalText }); + +export const organizationKind: RecordKind = recordKind( + organization.main, + { + legalName: optionalText, + publicEmail: optionalText, + organizationType: l.optional(l.array(l.string())), + urls: l.optional(l.array(urlItem)), + logo: optionalMedia, + foundedDate: optionalText, + longDescription: l.optional(longDescription), + langs: l.optional(l.array(l.string())), + visibility: optionalText, + }, + { logo: mediaTransform("image"), longDescription: longDescriptionTransform }, + { + references: { + location: references.one(() => locationKind), + additionalLocations: references.many(() => locationKind), + longDescription: longDescriptionReference, + }, + }, +); diff --git a/packages/sdk/src/organization/create-organization.test.ts b/packages/sdk/src/organization/create-organization.test.ts new file mode 100644 index 0000000..4adef8e --- /dev/null +++ b/packages/sdk/src/organization/create-organization.test.ts @@ -0,0 +1,470 @@ +import { describe, expect, it } from "vitest"; +import { CID, DID, fakePds, json } from "../test-utils/fake-pds.js"; +import { fakeRepo, HEAD, methods, refTo, writeOf } from "../test-utils/fake-repo.js"; +import { + type CreateOrganizationInput, + createOrganization, + type LeafletDocument, + type LocationInput, + OrganizationAlreadyExistsError, + RecordAlreadyExistsError, + WriteOutcomeUnknownError, + WriteRejectedError, +} from "./index.js"; + +const PROFILE = "app.certified.actor.profile"; +const ORGANIZATION = "app.certified.actor.organization"; +const LOCATION = "app.certified.location"; +const LEAFLET = "pub.leaflet.pages.linearDocument"; +const PROFILE_URI = `at://${DID}/${PROFILE}/self`; +const ORGANIZATION_URI = `at://${DID}/${ORGANIZATION}/self`; +const MiB = 1024 * 1024; +// CIDv1 (raw, sha-256) of the bytes "other": a head the repo moved to after it was read. +const OTHER_HEAD = "bafkreigzfgfbbunqonmdpxcl3bo2yza3b46o6j5epzovhjkpf47vwl6p7i"; + +const HEAD_METHOD = "com.atproto.sync.getLatestCommit"; +const READ = "com.atproto.repo.getRecord"; +const UPLOAD = "com.atproto.repo.uploadBlob"; +const WRITE = "com.atproto.repo.applyWrites"; + +const uriOf = (collection: string, rkey = "3k2a4b5c6d7e8") => `at://${DID}/${collection}/${rkey}`; +const png = (size = 3) => new Blob([new Uint8Array(size)], { type: "image/png" }); +const location = (name: string): LocationInput => ({ + lpVersion: "1.0", + srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84", + locationType: "coordinate-decimal", + location: { string: "27.47,90.17" }, + name, +}); +const withProfile = { [PROFILE_URI]: CID }; + +describe("createOrganization", () => { + it("creates the profile, the new locations and the organization in one request, after reading the head and both singletons", async () => { + const reused = uriOf(LOCATION, "3k2a4b5c6d7e9"); + const { context, requests, creates, swapCommits } = fakeRepo({ existing: { [reused]: CID } }); + + const result = await createOrganization(context, { + organization: { + legalName: "Phobjikha Conservation Society", + publicEmail: "hello@example.org", + organizationType: ["ngo", "cooperative"], + urls: [ + { url: "https://example.org/donate", label: "Donate" }, + { url: "https://example.org" }, + ], + logo: png(), + foundedDate: "2005-01-01T00:00:00.000Z", + langs: ["en"], + visibility: "public", + longDescription: "We plant native trees.", + location: location("Head office"), + additionalLocations: [{ uri: reused }, location("Field office")], + }, + profileIfMissing: { + displayName: "Phobjikha Conservation", + avatar: png(), + banner: "https://example.org/banner.png", + }, + }); + + // Everything is read first, the logo and the fallback avatar are uploaded, and one request writes. + expect(methods(requests)).toEqual([ + HEAD_METHOD, + READ, // the profile + READ, // the organization + READ, // the existing location + UPLOAD, + UPLOAD, + WRITE, + ]); + const writes = creates[0] ?? []; + expect(writes.map((write) => write.collection)).toEqual([ + PROFILE, + LOCATION, + LOCATION, + ORGANIZATION, + ]); + expect(swapCommits).toEqual([HEAD]); + const [profile, office, field, organization] = writes; + expect([profile?.rkey, organization?.rkey]).toEqual(["self", "self"]); + expect(profile?.value).toMatchObject({ + displayName: "Phobjikha Conservation", + avatar: { $type: "org.hypercerts.defs#smallImage" }, + banner: { $type: "org.hypercerts.defs#uri", uri: "https://example.org/banner.png" }, + }); + expect(organization?.value).toMatchObject({ + legalName: "Phobjikha Conservation Society", + publicEmail: "hello@example.org", + organizationType: ["ngo", "cooperative"], + urls: [ + { url: "https://example.org/donate", label: "Donate" }, + { url: "https://example.org" }, + ], + logo: { $type: "org.hypercerts.defs#smallImage", image: { mimeType: "image/png", size: 3 } }, + foundedDate: "2005-01-01T00:00:00.000Z", + langs: ["en"], + visibility: "public", + longDescription: { + $type: "org.hypercerts.defs#descriptionString", + value: "We plant native trees.", + }, + location: refTo(office as never), + additionalLocations: [{ uri: reused, cid: CID }, refTo(field as never)], + }); + // The result carries the exact URIs and CIDs the PDS computed for what it received. + expect(result).toEqual({ + organization: refTo(organization as never), + profile: { ...refTo(profile as never), created: true }, + location: { ...refTo(office as never), created: true }, + additionalLocations: [ + { uri: reused, cid: CID, created: false }, + { ...refTo(field as never), created: true }, + ], + }); + }); + + it.each<[string, CreateOrganizationInput["profileIfMissing"]]>([ + ["with fallback data", { displayName: "Not an update", avatar: png(), banner: png() }], + ["without fallback data", undefined], + ])( + "reuses an existing profile unchanged, uploads none of its fallback images and writes only the organization, %s", + async (_, profileIfMissing) => { + const { context, requests, creates } = fakeRepo({ existing: withProfile }); + + const result = await createOrganization(context, { + organization: { legalName: "Acme" }, + profileIfMissing, + }); + + expect(methods(requests)).toEqual([HEAD_METHOD, READ, READ, WRITE]); + expect((creates[0] ?? []).map((write) => write.collection)).toEqual([ORGANIZATION]); + expect(result).toEqual({ + organization: refTo(writeOf(creates[0] ?? [], ORGANIZATION)), + profile: { uri: PROFILE_URI, cid: CID, created: false }, + }); + }, + ); + + it("stores the logo as a URL without fetching it, and limits an uploaded logo to 5 MB before uploading", async () => { + const { context, requests, creates } = fakeRepo({ existing: withProfile }); + + await createOrganization(context, { + organization: { logo: "https://example.org/logo.png" }, + }); + expect(writeOf(creates[0] ?? [], ORGANIZATION).value.logo).toEqual({ + $type: "org.hypercerts.defs#uri", + uri: "https://example.org/logo.png", + }); + expect(methods(requests)).not.toContain(UPLOAD); + + await expect( + createOrganization(context, { organization: { logo: png(6 * MiB) } }), + ).rejects.toThrow(/organization\.logo cannot be stored as a small image/); + expect(methods(requests)).not.toContain(UPLOAD); + expect(creates).toHaveLength(1); + }); +}); + +describe("createOrganization locations", () => { + const first = uriOf(LOCATION, "3k2a4b5c6d7e1"); + const second = uriOf(LOCATION, "3k2a4b5c6d7e2"); + + it("keeps the primary and the additional locations apart, in order, and neither deduplicates nor rewrites existing ones", async () => { + const { context, creates } = fakeRepo({ + existing: { ...withProfile, [first]: CID, [second]: CID }, + }); + + const result = await createOrganization(context, { + organization: { + location: { uri: first }, + additionalLocations: [{ uri: first }, location("A"), { uri: second }, location("B")], + }, + }); + + const writes = creates[0] ?? []; + // Only the two new locations and the organization are written; the existing records are not. + expect(writes.map((write) => write.collection)).toEqual([LOCATION, LOCATION, ORGANIZATION]); + const [a, b] = writes.map(refTo); + expect(writes[2]?.value).toMatchObject({ + location: { uri: first, cid: CID }, + additionalLocations: [{ uri: first, cid: CID }, a, { uri: second, cid: CID }, b], + }); + expect(result.location).toEqual({ uri: first, cid: CID, created: false }); + expect(result.additionalLocations?.map(({ created }) => created)).toEqual([ + false, + true, + false, + true, + ]); + }); + + it("uploads and writes nothing when an existing location cannot be read", async () => { + const { context, requests } = fakeRepo({ existing: withProfile }); + + await expect( + createOrganization(context, { + organization: { logo: png(), location: { uri: first } }, + }), + ).rejects.toThrow(/cannot resolve .*the record was not found/); + + expect(methods(requests)).not.toContain(UPLOAD); + expect(methods(requests)).not.toContain(WRITE); + }); +}); + +describe("createOrganization longDescription", () => { + const document: LeafletDocument = { $type: LEAFLET, blocks: [] }; + const documentUri = uriOf("pub.leaflet.document"); + + it.each<[string, unknown, object, unknown]>([ + [ + "a string, inline", + "Plain text.", + { $type: "org.hypercerts.defs#descriptionString", value: "Plain text." }, + undefined, + ], + ["a Leaflet document, inline and as it is", document, document, undefined], + [ + "{ uri } as a strong reference to the record, which is read and never created", + { uri: documentUri }, + { $type: "com.atproto.repo.strongRef", uri: documentUri, cid: CID }, + { uri: documentUri, cid: CID, created: false }, + ], + ])("stores %s", async (_, longDescription, stored, reported) => { + const { context, requests, creates } = fakeRepo({ + existing: { ...withProfile, [documentUri]: CID }, + }); + + const result = await createOrganization(context, { + organization: { longDescription: longDescription as LeafletDocument }, + }); + + expect(writeOf(creates[0] ?? [], ORGANIZATION).value.longDescription).toEqual(stored); + expect(creates[0]).toHaveLength(1); + expect(result.longDescription).toEqual(reported); + expect(methods(requests).filter((method) => method === READ)).toHaveLength( + reported === undefined ? 2 : 3, + ); + }); +}); + +describe("createOrganization when the organization or the profile is missing", () => { + it("throws OrganizationAlreadyExistsError before uploading anything when the account has an organization", async () => { + const { context, requests } = fakeRepo({ + existing: { ...withProfile, [ORGANIZATION_URI]: CID }, + }); + + const error = await createOrganization(context, { + organization: { logo: png(), location: location("HQ") }, + profileIfMissing: { avatar: png() }, + }).catch((e) => e); + + expect(error).toBeInstanceOf(OrganizationAlreadyExistsError); + expect(error).toBeInstanceOf(RecordAlreadyExistsError); + expect(error).toBeInstanceOf(WriteRejectedError); + expect(error).toMatchObject({ + uri: ORGANIZATION_URI, + status: 400, + code: "InvalidSwap", + attempted: [], + }); + expect(error.message).toMatch(/never overwrites/); + expect(methods(requests)).toEqual([HEAD_METHOD, READ, READ]); + }); + + it("throws a TypeError naming profileIfMissing before uploading anything when the account has no profile and none is given", async () => { + const { context, requests } = fakeRepo(); + + const error = await createOrganization(context, { + organization: { logo: png(), location: location("HQ") }, + }).catch((e) => e); + + expect(error).toBeInstanceOf(TypeError); + expect(error.message).toMatch(/has no profile .*no profileIfMissing.*nothing was uploaded/s); + expect(methods(requests)).toEqual([HEAD_METHOD, READ, READ]); + }); +}); + +describe("createOrganization when a read fails", () => { + const notFound = () => json(400, { error: "RecordNotFound", message: "not found" }); + + // A PDS that answers the read of one collection with `failure` and every other record as absent. + const pdsFailingToRead = (collection: string, failure: () => Response) => + fakePds((request) => { + const url = new URL(request.path, "https://pds.test"); + if (url.pathname.endsWith(HEAD_METHOD)) return json(200, { cid: HEAD, rev: "3k2a4b5c6d7e8" }); + if (!url.pathname.endsWith(READ)) return json(500, { error: "Unexpected", message: "no" }); + return url.searchParams.get("collection") === collection ? failure() : notFound(); + }); + + it.each([ + ["the profile", PROFILE], + ["the organization", ORGANIZATION], + ])("never takes a failed read of %s as absence", async (_, collection) => { + const failures = [ + json(500, { error: "InternalServerError", message: "down" }), + json(403, { error: "Forbidden", message: "not allowed" }), + ]; + for (const failure of failures) { + const { context, requests } = pdsFailingToRead(collection, () => failure.clone()); + + const error = await createOrganization(context, { + organization: { logo: png() }, + profileIfMissing: { displayName: "Acme", avatar: png() }, + }).catch((e) => e); + + expect(error).not.toBeInstanceOf(TypeError); + expect(error).not.toBeInstanceOf(WriteRejectedError); + expect(error.message).toMatch( + new RegExp(`cannot check whether at://${DID}/${collection}/self exists`), + ); + // Nothing beyond the head and the two reads was sent: no upload and no write. + expect(methods(requests)).toEqual([HEAD_METHOD, READ, READ]); + } + }); + + it("does not read anything else when the latest commit cannot be read", async () => { + const { context, requests } = fakeRepo({ + getLatestCommit: () => json(500, { error: "InternalServerError", message: "down" }), + }); + + await expect( + createOrganization(context, { organization: {}, profileIfMissing: {} }), + ).rejects.toThrow(/cannot read the latest commit/); + + expect(methods(requests)).toEqual([HEAD_METHOD]); + }); +}); + +describe("createOrganization when the write does not go through", () => { + const input: CreateOrganizationInput = { + organization: { location: location("HQ") }, + profileIfMissing: { displayName: "Acme" }, + }; + + it("rejects the whole write when the repository changed after it was read, as when another call created the organization or the profile first", async () => { + const { context, requests, creates } = fakeRepo({ + onRequest: (method, state) => { + // The other write lands after the head was read, while the profile is being read. + if (method === READ) state.head = OTHER_HEAD; + }, + }); + + const error = await createOrganization(context, input).catch((e) => e); + + expect(error).toBeInstanceOf(WriteRejectedError); + expect(error).not.toBeInstanceOf(RecordAlreadyExistsError); + expect(error).toMatchObject({ status: 400, code: "InvalidSwap" }); + expect(error.message).toMatch(/the repository changed since it was read.*Call again/); + expect(error.attempted.map((ref: { uri: string }) => ref.uri)).toEqual([ + PROFILE_URI, + expect.stringContaining(`/${LOCATION}/`), + ORGANIZATION_URI, + ]); + // Nothing was applied and the SDK did not retry. + expect(creates).toEqual([]); + expect(methods(requests).filter((method) => method === WRITE)).toHaveLength(1); + }); + + it("lists every record it tried to create when the outcome is unknown, and says calling again is safe", async () => { + const { context } = fakeRepo({ applyWrites: () => json(500, {}) }); + + const error = await createOrganization(context, input).catch((e) => e); + + expect(error).toBeInstanceOf(WriteOutcomeUnknownError); + expect(error.attempted.map((ref: { uri: string }) => ref.uri)).toEqual([ + PROFILE_URI, + expect.stringContaining(`/${LOCATION}/`), + ORGANIZATION_URI, + ]); + expect(error.message).toMatch( + /calling createOrganization again is safe: the call reads the organization first.*the organization already exists/, + ); + // New locations have generated keys, so the message must not claim every record has a fixed key. + expect(error.message).not.toMatch(/fixed key/); + }); + + it("counts the profile against the write limit only when the call creates it", async () => { + const many = Array.from({ length: 199 }, (_, i) => location(`Office ${i}`)); + const created = fakeRepo({ existing: withProfile }); + + await createOrganization(created.context, { + organization: { additionalLocations: many }, + }); + expect(created.creates[0]).toHaveLength(200); + + const refused = fakeRepo(); + await expect( + createOrganization(refused.context, { + organization: { logo: png(), additionalLocations: many }, + profileIfMissing: { displayName: "Acme" }, + }), + ).rejects.toThrow(/would write 201 records, but one write holds at most 200/); + expect(methods(refused.requests)).toEqual([HEAD_METHOD, READ, READ]); + }); +}); + +describe("createOrganization input errors", () => { + it.each<[string, unknown, RegExp]>([ + [ + "a misspelled organization field", + { organization: { legalname: "Acme" } }, + /invalid organization: .*Allowed fields: legalName,/, + ], + [ + "an unknown top-level field", + { organization: {}, profileIfmissing: {} }, + /invalid input: .*Allowed fields: organization, profileIfMissing/, + ], + [ + "a misspelled field in a URL", + { organization: { urls: [{ url: "https://example.org", lable: "x" }] } }, + /Allowed fields: url, label/, + ], + [ + "an invalid fallback profile, although the account may have a profile", + { organization: {}, profileIfMissing: { displayName: 5 } }, + /invalid profileIfMissing: /, + ], + [ + "an existing location given as a bare string", + { organization: { location: uriOf(LOCATION) } }, + /organization\.location must be the fields of a new app\.certified\.location record, \{ uri \} of an existing one, but received a string/, + ], + [ + "an existing location of another record type", + { organization: { additionalLocations: [{ uri: uriOf("org.hypercerts.claim.rights") }] } }, + /organization\.additionalLocations\[0\] points at a record of type org\.hypercerts\.claim\.rights, but this field holds app\.certified\.location/, + ], + [ + "{ uri } mixed with the fields of a new location", + { organization: { location: { uri: uriOf(LOCATION), ...location("HQ") } } }, + /organization\.location combines `uri` with other fields/, + ], + [ + "a Leaflet document without its $type", + { organization: { longDescription: { blocks: [] } } }, + /must be a string, \{ uri \} of an existing record, or a Leaflet document/, + ], + ])("sends nothing for %s", async (_, input, message) => { + const { context, requests } = fakeRepo(); + + await expect(createOrganization(context, input as CreateOrganizationInput)).rejects.toThrow( + message, + ); + + expect(requests).toHaveLength(0); + }); + + it("writes nothing for an organization the lexicon rejects", async () => { + const { context, requests } = fakeRepo({ existing: withProfile }); + + await expect( + createOrganization(context, { organization: { langs: ["en", "es", "fr", "de"] } }), + ).rejects.toThrow( + /^createOrganization: organization is not a valid app\.certified\.actor\.organization record/, + ); + + expect(methods(requests)).not.toContain(WRITE); + }); +}); diff --git a/packages/sdk/src/organization/create-organization.ts b/packages/sdk/src/organization/create-organization.ts new file mode 100644 index 0000000..608a54d --- /dev/null +++ b/packages/sdk/src/organization/create-organization.ts @@ -0,0 +1,385 @@ +import { type CidString, l, type NsidString, type RecordKeyString } from "@atproto/lex"; +import * as organization from "@hypercerts-org/lexicon/app/certified/actor/organization"; +import * as profile from "@hypercerts-org/lexicon/app/certified/actor/profile"; +import { type ProfileInput, profileKind } from "../actor/build-profile.js"; +import type { SDKContext } from "../context.js"; +import { type BuildContext, createBuildContext, parseInput } from "../internal/build-context.js"; +import { describeError, isRecordNotFound } from "../internal/describe.js"; +import { strictObject } from "../internal/input.js"; +import { readRepoHead } from "../internal/read-repo-head.js"; +import { readRecord, type StoredRecord, type StrongRef } from "../internal/resolve-record-ref.js"; +import { + flattenSlots, + type NewSlot, + newSlots, + planNew, + prepareNew, + readBeforeWriting, + recordRef, + referencedResults, + referenceLookup, + type SupportingRecordRef, +} from "../internal/slots.js"; +import { + assertWithinWriteLimit, + RecordAlreadyExistsError, + submitWrites, +} from "../internal/submit-writes.js"; +import { type OrganizationInput, organizationKind } from "./build-organization.js"; + +const OPERATION = "createOrganization"; + +// Why a repeat call after an unknown outcome cannot duplicate the new locations, which have +// generated keys: see `retrySafeReason`. +const RETRY_SAFE_REASON = + "the call reads the organization first, so a repeat call either creates everything or fails because the organization already exists"; + +// Both lexicons fix their record key to `self`. +const SELF = "self" as RecordKeyString; + +/** The input of {@link createOrganization}. */ +export interface CreateOrganizationInput { + /** The organization's own metadata. See {@link OrganizationInput}. */ + organization: OrganizationInput; + /** + * The data to create the account's profile from, used only if the account has no profile. An + * existing profile is reused unchanged and this is ignored, apart from being validated: it is + * never an update, and its `avatar` and `banner` are not uploaded. Required when the account has + * no profile. See {@link ProfileInput}. + */ + profileIfMissing?: ProfileInput | undefined; +} + +/** + * The result of {@link createOrganization}. + * + * @remarks + * `location` and `additionalLocations` mirror the input: `additionalLocations[i]` belongs to the + * input entry at the same index, whether it was created or reused. Filter on `created` for only the + * records this call wrote. + */ +export interface CreateOrganizationResult { + /** The URI and CID of the new organization record. */ + organization: StrongRef; + /** + * The account's profile. `created` is `true` when this call wrote it from `profileIfMissing`, + * `false` when the account already had one, which is unchanged; its `cid` is then the one the SDK + * read. + */ + profile: SupportingRecordRef; + /** The primary location, when the input had `location`. */ + location?: SupportingRecordRef; + /** The additional locations, in input order, when the input had `additionalLocations`. */ + additionalLocations?: readonly SupportingRecordRef[]; + /** + * The document the input's `longDescription` pointed at, with the CID that was stored. Present + * only for a `{ uri }` description; `created` is `false`. + */ + longDescription?: SupportingRecordRef; +} + +/** + * The account already has an organization record, so `createOrganization` did not write one. + * + * @remarks + * Nothing was uploaded or written: the existing organization is untouched. `uri` is the existing + * record and `attempted` is empty, because the SDK found the record before sending anything. + * Extends {@link RecordAlreadyExistsError}, which extends {@link WriteRejectedError}, so code that + * handles either also handles this; `status` is `400` and `code` is `InvalidSwap`, as the PDS + * reports a taken key. + */ +export class OrganizationAlreadyExistsError extends RecordAlreadyExistsError { + override readonly name = "OrganizationAlreadyExistsError"; +} + +const inputSchema = strictObject({ + organization: l.unknown(), + profileIfMissing: l.optional(l.unknown()), +}); + +/** + * Creates the account's organization record (`app.certified.actor.organization`), and its profile + * if it has none, in one atomic write. + * + * @remarks + * An account has at most one organization record and one profile, both at the key `self`. The SDK + * reads both from the account's PDS before it uploads or writes anything: + * - The account already has an organization: {@link OrganizationAlreadyExistsError}. Nothing is + * overwritten, merged or updated, and the SDK has no operation that updates an organization. + * - The account has a profile: it is reused exactly as it is. `profileIfMissing` is not applied to + * it, and its `avatar` and `banner` are not uploaded. + * - The account has no profile and `profileIfMissing` is set: the profile is created from it, in + * the same write. + * - The account has no profile and `profileIfMissing` is not set: a {@link TypeError}. The SDK + * does not create an empty profile. An explicit `profileIfMissing: {}` is data, and creates one + * with only its `createdAt`. + * + * A read that fails for any reason other than "the record does not exist" (a network error, a + * server error, a refused permission) throws; it is never taken as "absent". + * + * Each location (`location`, and each of `additionalLocations`) is the data of a new location or + * `{ uri }` of an existing `app.certified.location` record, which is read to learn its CID and + * reused unchanged. A bare URI string is not accepted. `longDescription` takes a string, a + * {@link LeafletDocument} stored inline, or `{ uri }` of an existing record, which is referenced + * and never created. Nothing is deduplicated: the primary location may repeat in + * `additionalLocations`, and the SDK does not notice. `createdAt` defaults to the time of the call. + * + * The new profile (if any), the new locations and the organization are created in a single + * `com.atproto.repo.applyWrites` request, which the PDS commits as a whole: all of them exist + * afterwards, or none does. One write holds at most 200 records. + * + * Concurrent changes: the write is conditional on the account not having changed since the profile + * and the organization were read, so another call creating either one in the meantime cannot make + * the decision "reuse or create the profile" stale. If it did change, this throws + * {@link WriteRejectedError} with `code` `"InvalidSwap"`; see there. + * + * The order is: validate the input, read the latest commit, read the profile and the organization, + * read the existing records the input points at, upload blobs, write. An invalid input, an existing + * organization, a missing profile without `profileIfMissing`, a read that fails, or too many records + * stops before any upload. Blobs (a `Blob` or `File` logo, a new location's `{ blob }`, and the + * profile's images when the profile is created) are uploaded before the write and are not rolled + * back if it fails; see {@link uploadBlob}. + * + * The OAuth session needs `create` on `app.certified.actor.organization`, and on + * `app.certified.actor.profile` and `app.certified.location` when this call creates them. Unlike + * {@link createProfile}, no `update` permission is needed. + * + * This creates records in the repository the client is signed in to. It does not create accounts, + * and has no connection to a group service. + * + * @param context - The shared context from {@link createSDKContext}. Its client must be + * authenticated; the records are created in that account's repo. + * @param input - The organization and the fallback profile. See {@link CreateOrganizationInput}. + * @returns The organization's URI and CID, the profile's with whether it was created or reused, + * and the locations. See {@link CreateOrganizationResult}. + * @throws {@link TypeError} If `input` has an unknown field or a value the lexicons do not allow, a + * location that is a bare string or a `{ uri }` of another record type, `{ uri }` combined with + * record fields, more new records than one write holds, or the account has no profile and + * `profileIfMissing` is not set. The message names the field. Nothing was written. Blobs may already + * have been uploaded when a lexicon rule rejects a record. + * @throws {@link Error} If the client is not authenticated, the latest commit, the profile, the + * organization or an existing record the input points at cannot be read, or an upload fails. Nothing + * was written. + * @throws {@link OrganizationAlreadyExistsError} If the account already has an organization. + * Nothing was uploaded or written. + * @throws {@link WriteRejectedError} If the PDS rejected the write (HTTP 4xx). With `code` + * `"InvalidSwap"` the repository changed after it was read; call again. + * {@link OrganizationAlreadyExistsError} has the same `code` but is not retryable: rule out + * `instanceof RecordAlreadyExistsError` first. + * @throws {@link WriteOutcomeUnknownError} If there was no usable answer from the PDS. Calling again + * is safe even though new locations get fresh record keys: the call reads the organization first, + * so it either creates everything or throws {@link OrganizationAlreadyExistsError}, which then + * means the first attempt succeeded and no second set of locations or profile is created. The new + * records are the ones in `attempted` of the first error. + * @throws {@link WriteResultMismatchError} If the PDS reported different URIs or CIDs than the SDK + * computed. + * + * @example Creating an organization and, if the account has none, its profile + * ```ts + * import { createOrganization } from "@hypercerts-org/sdk/organization"; + * + * // `context` comes from createSDKContext; `logoFile` is a File, for example from an + * // . + * const { organization, profile, location } = await createOrganization(context, { + * organization: { + * legalName: "Phobjikha Conservation Society", + * organizationType: ["ngo"], + * urls: [{ url: "https://example.org/donate", label: "Donate" }], + * logo: logoFile, // uploaded; a URL string would be stored as it is + * longDescription: "We plant native trees in the Phobjikha valley.", + * location: { + * lpVersion: "1.0", + * srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84", + * locationType: "country-code", + * location: { string: "BT" }, + * }, // created + * additionalLocations: [ + * { uri: "at://did:plc:abc123/app.certified.location/3k2a4b5c6d7e8" }, // reused + * ], + * }, + * // Used only if the account has no profile yet; ignored (and its images not uploaded) otherwise. + * profileIfMissing: { displayName: "Phobjikha Conservation", avatar: "https://example.org/a.png" }, + * }); + * console.log(organization.uri); // at:///app.certified.actor.organization/self + * console.log(profile.created); // false when the account already had a profile + * ``` + * + * @example An organization already exists + * ```ts + * import { createOrganization, OrganizationAlreadyExistsError } from "@hypercerts-org/sdk/organization"; + * + * try { + * await createOrganization(context, { organization: { legalName: "Acme" } }); + * } catch (error) { + * if (!(error instanceof OrganizationAlreadyExistsError)) throw error; + * // Nothing was uploaded or written, and the SDK cannot update the existing organization. + * console.log(error.uri); + * } + * ``` + * + * @example A missing profile needs `profileIfMissing` + * ```ts + * import { createOrganization } from "@hypercerts-org/sdk/organization"; + * + * // TypeError if the account has no profile: the SDK does not create an empty one. + * await createOrganization(context, { organization: { legalName: "Acme" } }); + * ``` + * + * @example Reusing an existing location takes `{ uri }`, not a string + * ```ts + * import { createOrganization } from "@hypercerts-org/sdk/organization"; + * + * await createOrganization(context, { + * organization: { + * location: "at://did:plc:abc123/app.certified.location/3k2a4b5c6d7e8", // TypeError + * }, + * profileIfMissing: { displayName: "Acme" }, + * }); + * ``` + * + * @example Calling again when the repository changed in between + * ```ts + * import { + * createOrganization, + * RecordAlreadyExistsError, + * WriteRejectedError, + * } from "@hypercerts-org/sdk/organization"; + * + * try { + * return await createOrganization(context, input); + * } catch (error) { + * if ( + * error instanceof WriteRejectedError && + * error.code === "InvalidSwap" && + * // OrganizationAlreadyExistsError has the same code, but calling again cannot fix it. + * !(error instanceof RecordAlreadyExistsError) + * ) { + * // Another write to the account landed between the reads and the write. Nothing was written, + * // so it is safe to call again; everything is read afresh. + * return await createOrganization(context, input); + * } + * throw error; + * } + * ``` + */ +export async function createOrganization( + context: SDKContext, + input: CreateOrganizationInput, +): Promise { + const build = createBuildContext(context, OPERATION); + const { organization: organizationSlot, fallback } = planInput(build, input); + + const start = await readStartingPoint(build); + if (start.organization !== undefined) throw organizationExists(start.organization.ref.uri); + const profilePlan = planProfile(build, start.profile, fallback); + + // A reused profile is not in the write, so its images are never uploaded. + const slots = flattenSlots( + profilePlan.kind === "created" ? [profilePlan.slot, organizationSlot] : [organizationSlot], + ); + assertWithinWriteLimit(OPERATION, newSlots(slots).length); + const existing = await readBeforeWriting(build, slots, { checkKeys: false }); + const created = await prepareNew(slots, existing); + + // The organization has a fixed key and was found absent above, so calling again after an unknown + // outcome creates everything or finds the organization, and never makes a copy. + await submitWrites(context, build.did, [...created.values()], OPERATION, { + swapCommit: start.head, + retrySafe: true, + retrySafeReason: RETRY_SAFE_REASON, + }); + + const refOf = referenceLookup(existing, created); + return { + organization: refOf(organizationSlot), + profile: + profilePlan.kind === "created" + ? recordRef(profilePlan.slot, created, refOf) + : { ...profilePlan.ref, created: false }, + ...referencedResults(organizationSlot, created, refOf), + }; +} + +// Validates everything the caller passed before any request is sent, the fallback profile included +// even when it ends up unused, so an input error does not depend on the account's state. +function planInput( + build: BuildContext, + input: unknown, +): { organization: NewSlot; fallback: NewSlot | undefined } { + const parsed = parseInput(build, "input", inputSchema, input); + return { + organization: planNew(build, "organization", organizationKind, parsed.organization), + fallback: + parsed.profileIfMissing === undefined + ? undefined + : planNew(build, "profileIfMissing", profileKind, parsed.profileIfMissing), + }; +} + +interface StartingPoint { + head: CidString; + profile: StoredRecord | undefined; + organization: StoredRecord | undefined; +} + +// What the write is based on. The head is read first, so a change to either record after it moves +// the head past the one the write is conditional on: see `readRepoHead`. +async function readStartingPoint(build: BuildContext): Promise { + const head = await readRepoHead(build.context, build.did, OPERATION); + const [profileRecord, organizationRecord] = await Promise.all([ + readSingleton(build, profile.main.$type), + readSingleton(build, organization.main.$type), + ]); + return { head, profile: profileRecord, organization: organizationRecord }; +} + +type ProfilePlan = { kind: "reused"; ref: StrongRef } | { kind: "created"; slot: NewSlot }; + +// Reuse the profile the account has, or create it from the fallback. +function planProfile( + build: BuildContext, + existingProfile: StoredRecord | undefined, + fallback: NewSlot | undefined, +): ProfilePlan { + if (existingProfile !== undefined) return { kind: "reused", ref: existingProfile.ref }; + if (fallback === undefined) throw missingProfile(singletonUri(build, profile.main.$type)); + return { kind: "created", slot: fallback }; +} + +const singletonUri = (build: BuildContext, collection: NsidString) => + `at://${build.did}/${collection}/${SELF}`; + +// The record at `self`, or `undefined` when the PDS says there is none. Any other failure throws: a +// record that could not be read is not a record that is absent. +async function readSingleton( + build: BuildContext, + collection: NsidString, +): Promise { + const uri = singletonUri(build, collection); + try { + return await readRecord(build.context, uri, OPERATION); + } catch (error) { + // `readRecord` keeps the client's error as the cause of its own. + const cause = error instanceof Error ? error.cause : undefined; + if (isRecordNotFound(cause)) return undefined; + throw new Error( + `${OPERATION}: cannot check whether ${uri} exists (${describeError(cause ?? error)}), so nothing was uploaded or written.`, + { cause: error }, + ); + } +} + +function organizationExists(uri: string): OrganizationAlreadyExistsError { + return new OrganizationAlreadyExistsError( + `${OPERATION}: the account already has an organization (${uri}), so nothing was uploaded or written and the existing one is unchanged. ${OPERATION} only creates an organization; it never overwrites one, and the SDK cannot update an organization yet.`, + uri, + [], + { status: 400, code: "InvalidSwap" }, + ); +} + +function missingProfile(uri: string): TypeError { + return new TypeError( + `${OPERATION}: the account has no profile (${uri} does not exist) and the input has no profileIfMissing to create one from, so nothing was uploaded or written. Pass profileIfMissing with the profile's data (for example { displayName: "Acme" }), or create the profile first with createProfile.`, + ); +} diff --git a/packages/sdk/src/organization/index.ts b/packages/sdk/src/organization/index.ts new file mode 100644 index 0000000..eb4a4de --- /dev/null +++ b/packages/sdk/src/organization/index.ts @@ -0,0 +1,19 @@ +// Entry point for @hypercerts-org/sdk/organization. + +// The types of the inputs that `OrganizationInput` and `CreateOrganizationInput` embed, and the +// errors a write can end with. +export type { ProfileInput } from "../actor/build-profile.js"; +export type { LeafletDocument } from "../internal/long-description.js"; +export type { StrongRef } from "../internal/resolve-record-ref.js"; +export type { ExistingRecord, SupportingRecordRef } from "../internal/slots.js"; +export { + RecordAlreadyExistsError, + WriteError, + WriteOutcomeUnknownError, + WriteRejectedError, + WriteResultMismatchError, +} from "../internal/submit-writes.js"; +export type { LocationInput } from "../location/build-location.js"; +export type { OrganizationInput, OrganizationUrl } from "./build-organization.js"; +export type { CreateOrganizationInput, CreateOrganizationResult } from "./create-organization.js"; +export { createOrganization, OrganizationAlreadyExistsError } from "./create-organization.js";