@oxyhq/contracts 0.23.0 → 0.25.0

package/dist/types/followGraph.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The follow graph wire contract (`/v2/follows`).
+ *
+ * These types are the boundary between the API that owns the graph and every
+ * application that reads it. They live here — not in the API and not in the
+ * SDK — because both ends have to agree, and a shape defined on one side is a
+ * shape the other side re-declares slightly differently within a release or two.
+ *
+ * ## Why the state is three fields and not a boolean
+ *
+ * A user can follow something globally and turn it off in ONE application. That
+ * is a state the user themselves created, so the client has to be able to see
+ * it and say so — "following, but not shown here" is a sentence a boolean
+ * cannot express. `globalState`, `applicationMode` and `effectiveState` are
+ * therefore reported separately, and only the last one answers "does this
+ * appear in my feed right now".
+ *
+ * ## Why kinds are strings
+ *
+ * `FollowTargetKind` is a plain `string`, not a union. Applications register
+ * their own kinds at runtime (`mercaria.store`, `syra.artist`), so a union here
+ * would mean every new application in the ecosystem needs a release of this
+ * package before it can follow anything. The namespace rule is enforced by the
+ * database, which is the one place that can enforce it for applications this
+ * package has never heard of.
+ */
+/**
+ * A registered target kind, always `<namespace>.<thing>`.
+ *
+ * The namespace is the owning application's, so two applications cannot define
+ * or silently redefine each other's kinds.
+ */
+export type FollowTargetKind = string;
+/**
+ * Where a relationship stands globally — the user's own decision, independent
+ * of any application. Mirrors the database's own enum, which is the authority.
+ *
+ * `requested` is a real state and not a transient one: a private account has to
+ * accept, and until it does the user has asked and is waiting. A client that
+ * renders it as "not following" invites a second request that changes nothing.
+ */
+export type FollowState = 'none' | 'requested' | 'active' | 'rejected';
+/**
+ * What this application should DO right now — the field a button renders.
+ *
+ * Note that "never followed" and "following, but switched off here" both come
+ * back as `not_following`, because the answer to "does this appear in my feed"
+ * is the same for both. They are still distinguishable, and a UI explaining
+ * itself must distinguish them: it is `globalState === 'active'` with
+ * `applicationMode === 'disabled'`.
+ */
+export type FollowEffectiveState = 'not_following' | 'requested' | 'following';
+/**
+ * What ONE application does with a relationship.
+ *
+ * `inherit` is the default and means "whatever the user decided globally".
+ * `disabled` is the interesting one: the user still follows, this application
+ * just does not act on it — which is what makes "follow everywhere, mute here"
+ * possible without the user losing the follow.
+ */
+export type FollowApplicationMode = 'inherit' | 'enabled' | 'disabled';
+/** A thing that can be followed. */
+export interface FollowTarget {
+    id: string;
+    /**
+     * The stable, global identity of the thing — an Oxy URI for local objects, an
+     * ActivityPub actor URI for remote ones. What makes "the same target" the
+     * same across applications and across servers.
+     */
+    uri: string;
+    kind: FollowTargetKind;
+    /**
+     * A cached display snapshot (name, handle, avatar). Present so a follow list
+     * can render without one lookup per row; never authoritative — the owning
+     * application always holds the current version.
+     */
+    metadata?: Record<string, unknown>;
+}
+/** One row of the user's central follow list. */
+export interface FollowRecord {
+    relationshipId: string;
+    target: FollowTarget;
+    globalState: FollowState;
+    applicationMode: FollowApplicationMode;
+    /**
+     * Whether this follow acts in the requesting application right now — the
+     * same field a button renders. List rows carry it so a follow list can seed
+     * `FollowTargetButton` without recomputing the server's derivation.
+     */
+    effectiveState: FollowEffectiveState;
+    /**
+     * Where the user was when they followed. Provenance for the audit trail and
+     * for notification routing — never authority: this application cannot undo
+     * what another one recorded.
+     */
+    originApplicationId: string | null;
+    /** Set only on a timed follow. ISO-8601. */
+    expiresAt?: string;
+    createdAt: string;
+}
+/**
+ * The three-part answer to "am I following this".
+ *
+ * `effectiveState` is what a button renders. The other two are what an
+ * explanation renders, and a client that shows a disabled follow as "not
+ * following" will be asked why the button does nothing.
+ */
+export interface FollowStatus {
+    /** Absent when nothing has ever been followed. Every other operation needs it. */
+    relationshipId?: string;
+    globalState: FollowState;
+    applicationMode: FollowApplicationMode;
+    /** `following` only when followed globally AND not disabled here. */
+    effectiveState: FollowEffectiveState;
+    expiresAt?: string;
+}
+/**
+ * `PUT /v2/follows/:targetId` — `created: false` means it already existed.
+ *
+ * Carries the whole resulting status rather than a couple of fields off it, so
+ * a client can store the answer instead of reconstructing one. Reconstructing
+ * is where an optimistic update and the settled value drift: the derivation of
+ * `effectiveState` lives on the server, and a client recomputing it is a second
+ * implementation of a rule that has one.
+ */
+export interface FollowMutation {
+    relationshipId: string;
+    created: boolean;
+    status: FollowStatus;
+}
+/** `DELETE /v2/follows/:relationshipId` — `removed: false` means it was already gone. */
+export interface UnfollowMutation {
+    removed: boolean;
+}
+/** `GET /v2/me/follows` */
+export interface FollowListPage {
+    follows: FollowRecord[];
+    /** Absent when the last page has been reached. */
+    nextCursor?: string;
+}
+/**
+ * Options for `PUT /v2/follows/:targetId`.
+ *
+ * `expiresIn` is the timed follow — seconds from now. Bounded server-side,
+ * because an unbounded value is indistinguishable from a permanent follow the
+ * user believes will end.
+ */
+export interface FollowOptions {
+    expiresIn?: number;
+}

package/dist/types/index.d.ts

@@ -37,6 +37,7 @@ export { MODERATION_SEVERITIES, MODERATION_FINDING_SCOPES, MODERATION_ATTRIBUTIO
 export type { ModerationSeverity, ModerationFindingScope, ModerationAttribution, ModerationDecisionStatus, ModerationEffectType, ModerationEffectStatus, ModerationEffectSkipReason, ConductStrikeStatus, ConductStanding, ContributionTier, PersonhoodStatusValue, IdentityBindingType, IdentityBindingStatus, ApplicationModerationStanding, ModerationFinding, ModerationDecisionEventSubject, ModerationPolicyVersions, ModerationDecisionEvent, FinalizeModerationDecisionInput, ReverseModerationEffectInput, ModerationEffect, ApplyModerationDecisionResult, ReverseModerationEffectResult, RegisterIdentityBindingInput, IdentityBinding, ReputationPersonhood, ReputationContribution, ReputationConduct, ReputationReporting, ReputationReviewing, ReputationContextualInfluence, ApplicationModerationTrust, } from './moderationReputation';
 export { linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links';
 export type { LinkPreviewStatus, LinkPreview, LinkPreviewBatchRequest, LinkPreviewBatchResponse, } from './links';
+export type { FollowTargetKind, FollowState, FollowEffectiveState, FollowApplicationMode, FollowTarget, FollowRecord, FollowStatus, FollowMutation, UnfollowMutation, FollowListPage, FollowOptions, } from './followGraph';
 export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceBackgroundCredentialResponseSchema, deviceBackgroundTokenRequestSchema, deviceBackgroundTokenResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession';
 export type { SessionAccount, DeviceSessionState, ActiveToken, DeviceSessionSync, DeviceTokenMintRequest, DeviceTokenMintResponse, DeviceBackgroundCredentialResponse, DeviceBackgroundTokenRequest, DeviceBackgroundTokenResponse, SessionAccountsChangedReason, SessionAccountsChangedEvent, } from './deviceSession';
 export { loginResultSchema, } from './deviceBoot';

package/dist/types/oxyRecordTypes.d.ts

@@ -1,31 +1,59 @@
 /**
  * Oxy-scoped signed-record types.
  *
- * The base `signedRecordEnvelopeSchema` (`./identity`) now treats `type` as an
- * OPEN, non-empty string so ANY Oxy app may define its own record categories
- * (e.g. `app.mention.*`'s `app_record`) on the shared envelope grammar. The Oxy
- * identity/civic/node STORE, however, accepts ONLY the closed set of categories
- * it knows how to verify and materialize — this module is that closed set.
+ * The base `signedRecordEnvelopeSchema` (`./identity`) treats `type` as an OPEN,
+ * non-empty string so ANY Oxy app may sign on the shared envelope grammar. The
+ * Oxy STORE re-narrows it to the closed set in this module — a `type` outside it
+ * is rejected as `invalid_envelope`.
  *
- * `oxySignedRecordTypeSchema` is the runtime gate the Oxy store re-narrows with
- * (the API's `verifyEnvelope` rejects any `type` outside it; the Mongoose
- * `SignedRecord.type` enum is derived from `.options`); `OxySignedRecordType` is
- * the matching compile-time union the SDK identity/civic mixins type against.
+ * `oxySignedRecordTypeSchema` is that runtime gate (the API's `verifyEnvelope`
+ * re-narrows with it; the Mongoose `SignedRecord.type` enum and the Postgres
+ * CHECK on `signed_records.type` are both derived from `.options`);
+ * `OxySignedRecordType` is the matching compile-time union the SDK
+ * identity/civic mixins type against.
  *
  * The signing input INCLUDES `type`, so this set is part of the signed bytes —
- * a record cannot have its category swapped after signing.
+ * a record cannot have its category swapped after signing, and a value once
+ * signed can never be renamed.
  *
  * v1 only ever carried `identity` / `profile` (already in production); v2 added
  * the civic record types (reputation attestations, real-life / peer validations,
  * personhood vouches, verifiable credentials) and the user-node registration
- * record. Every value here is an Oxy `app.oxy.*` (or legacy v1) category — an
- * app's own `type` (e.g. `app_record`) is intentionally NOT in this set and is
- * rejected by the Oxy store.
+ * record.
+ *
+ * ## Why `app_record` is here, when it deliberately was not
+ *
+ * This set used to hold Oxy's own categories only, and said so: an app's `type`
+ * was "intentionally NOT in this set". The reason given was that the store
+ * accepts only what it knows how to **verify and materialize**. Verification
+ * turned out not to argue for the exclusion — the engine verifies a signature
+ * against the subject's keys whatever the category says — and materialization
+ * is the app's job, not the store's: an app projects its own feed tables from
+ * records it reads back.
+ *
+ * What changed is the decision the exclusion blocked. One chain per PERSON, held
+ * by Oxy, is the ecosystem substrate: apps append their records to the subject's
+ * one chain instead of each keeping a private chain for the same person. A
+ * closed set that admits no app category makes that unrepresentable.
+ *
+ * `app_record` is ONE value rather than an open lane, and the lexicon lives in
+ * the envelope's `collection` (`app.mention.feed.post`, `app.syra.*`), which the
+ * store denormalizes to `signed_records.nsid` and indexes. So a new app needs no
+ * change here — it picks its own collection namespace and signs `app_record`,
+ * exactly as Mention already does in production. Keeping the set closed is what
+ * keeps the CHECK a real constraint.
+ *
+ * **Admitting the category is not the whole of that decision.** Two gates sit
+ * beside it and are unchanged: an app record must arrive as a v2 (chained)
+ * envelope, and `oxyVerificationResolver` accepts exactly one custodial issuer
+ * (`OXY_DID`). So a record a user signs themselves verifies here today, while
+ * one an app signs custodially under its OWN issuer DID does not — that needs a
+ * separate, deliberate answer about which issuers may write to a person's chain.
  *
  * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
  */
 import { z } from 'zod';
-export declare const oxySignedRecordTypeSchema: z.ZodEnum<["identity", "profile", "reputation_attestation", "real_life_attestation", "validation_verdict", "personhood_vouch", "credential", "node"]>;
+export declare const oxySignedRecordTypeSchema: z.ZodEnum<["identity", "profile", "reputation_attestation", "real_life_attestation", "validation_verdict", "personhood_vouch", "credential", "node", "app_record"]>;
 /**
  * The closed set of record categories the Oxy identity/civic/node store accepts.
  * The base envelope `type` is an open string; this is what the Oxy store

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/contracts",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "OxyHQ API contracts — single source of truth for request/response Zod schemas and inferred types, shared by the backend and the client SDKs",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -26,6 +26,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "NOTICE",
     "dist"
   ],
   "keywords": [
@@ -42,7 +43,7 @@
     "directory": "packages/contracts"
   },
   "author": "OxyHQ",
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "homepage": "https://oxy.so",
   "engines": {
     "node": ">=18.0.0"