@oxy.so/contracts 1.4.0 → 1.5.0

package/dist/esm/index.js

@@ -178,3 +178,5 @@ export { AUTONOMY_LEVELS, CAPABILITY_PACKAGES, autonomyLevelSchema, capabilityPa
 export { emailContextAddressSchema, emailContextMailboxSchema, emailContextMessageSchema, emailAgentContextSchema, } from './emailAgentContext.js';
 export { inboxComposeRequestSchema, inboxDailyBriefRequestSchema, inboxNaturalSearchRequestSchema, inboxMessageInferenceParamsSchema, inboxInferenceTextResponseSchema, inboxNaturalSearchResponseSchema, inboxSmartRepliesResponseSchema, inboxThreadSummaryResponseSchema, inboxInferenceStreamEventSchema, } from './inference/inbox.js';
 export * from './externalIdentity.js';
+export * from './linkedAccounts.js';
+export * from './notifications.js';

package/dist/esm/linkedAccounts.js

@@ -0,0 +1,90 @@
+/**
+ * Wire contract for Oxy linked accounts — external accounts (any Mastodon-API
+ * server, Bluesky) a LOCAL Oxy user has proven they own by completing an OAuth
+ * authorization there.
+ *
+ * Every response schema is `.strict()` and carries no field a third-party token
+ * could occupy: Oxy uses the OAuth flow only to learn which account authorized
+ * it, then discards the token. See `docs/identity/linked-accounts.md`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+export const LINKED_ACCOUNT_NETWORKS = ['activitypub', 'atproto'];
+export const linkedAccountNetworkSchema = z.enum(LINKED_ACCOUNT_NETWORKS);
+/**
+ * `POST /linked-accounts/:network/start`.
+ *
+ * - `instance` (activitypub): `mastodon.social`, `https://mastodon.social` or
+ *   `@user@mastodon.social`.
+ * - `handle` (atproto): a handle (`alice.bsky.social`) or a DID.
+ * - `returnTo` + `clientId`: where the browser lands afterwards, with
+ *   `?link_code=` or `?link_error=`. `returnTo` must exactly match a redirect
+ *   URI registered on the TRUSTED (first-party) application `clientId` names.
+ */
+export const startLinkedAccountRequestSchema = z
+    .object({
+    instance: z.string().trim().min(1).max(320).optional(),
+    handle: z.string().trim().min(1).max(320).optional(),
+    clientId: z.string().trim().min(1).max(256),
+    returnTo: z.string().trim().min(1).max(2048),
+})
+    .strict();
+export const startLinkedAccountResponseSchema = z
+    .object({
+    authorizeUrl: z.string().url(),
+    expiresAt: z.string().datetime(),
+})
+    .strict();
+/**
+ * `POST /linked-accounts/complete`, with the session of the user who STARTED
+ * the flow: `code` is the one-time `link_code` the callback appended to
+ * `returnTo`. It expires five minutes after the callback. Presented by any
+ * other user it is refused (403) and burned.
+ */
+export const completeLinkedAccountRequestSchema = z
+    .object({ code: z.string().trim().min(1).max(256) })
+    .strict();
+/** One live linked account, as its owner sees it. */
+export const linkedAccountSchema = z
+    .object({
+    id: z.string().min(1),
+    network: linkedAccountNetworkSchema,
+    /** `username@domain` for ActivityPub; the DID for atproto. */
+    accountKey: z.string().min(1),
+    /** ActivityPub actor id, or the DID for atproto. */
+    actorUri: z.string().min(1),
+    handle: z.string().min(1),
+    host: z.string().min(1),
+    proofMethod: z.literal('oauth'),
+    verifiedAt: z.string().datetime(),
+    createdAt: z.string().datetime(),
+})
+    .strict();
+export const completeLinkedAccountResponseSchema = z
+    .object({ linkedAccount: linkedAccountSchema })
+    .strict();
+export const linkedAccountListResponseSchema = z
+    .object({ linkedAccounts: z.array(linkedAccountSchema) })
+    .strict();
+/**
+ * `GET /linked-accounts/by-user/:userId` (service token with the privileged
+ * `linked-accounts:read`). Adds `federatedUserId`: the FEDERATED shadow user Oxy
+ * already holds for that external account, if any — the anchor for adopting
+ * content Oxy federated in before the account was linked.
+ */
+export const serviceLinkedAccountSchema = linkedAccountSchema
+    .extend({ federatedUserId: z.string().min(1).nullable() })
+    .strict();
+export const serviceLinkedAccountListResponseSchema = z
+    .object({ userId: z.string().min(1), linkedAccounts: z.array(serviceLinkedAccountSchema) })
+    .strict();
+/**
+ * Error codes the callback appends as `?link_error=<code>` to `returnTo`. An
+ * account already linked to someone else is reported by `/complete` (409).
+ */
+export const LINKED_ACCOUNT_CALLBACK_ERRORS = [
+    'access_denied',
+    'verification_failed',
+    'provider_unavailable',
+];

package/dist/esm/notifications.js

@@ -0,0 +1,78 @@
+/**
+ * The closed set of Oxy in-app notification types — owned here so the API's
+ * CHECK constraint (`notifications.type`), its request validation and the SDK
+ * all read one tuple.
+ *
+ * `system` is a message from an Oxy service about the recipient's OWN account
+ * (Oxy Move's "your migration finished"): the actor is the recipient, and the
+ * entity is their profile or an `app` id. It is the only type an actor does not
+ * cause.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+export const OXY_NOTIFICATION_TYPES = [
+    'like',
+    'reply',
+    'mention',
+    'follow',
+    'repost',
+    'quote',
+    'welcome',
+    'system',
+];
+/**
+ * What a notification's `entityId` names.
+ *
+ * `app` means `entityId` is an OPAQUE id in the notifying application's own
+ * namespace (Oxy Move's migration job id). Oxy never resolves it; it exists so
+ * a `system` notification about something that is not a post or a profile does
+ * not have to pretend to be one. Valid only with `type: 'system'`.
+ */
+export const OXY_NOTIFICATION_ENTITY_TYPES = ['post', 'reply', 'profile', 'app'];
+/** Length caps on the text a `system` notification carries (enforced by CHECKs too). */
+export const OXY_SYSTEM_NOTIFICATION_TITLE_MAX = 120;
+export const OXY_SYSTEM_NOTIFICATION_MESSAGE_MAX = 500;
+export const OXY_NOTIFICATION_URL_MAX = 2048;
+/**
+ * `POST /notifications` (service token with `notifications:write`).
+ *
+ * Only a `system` notification carries text: `title` and `message` are REQUIRED
+ * for it and stored, and `url` is an optional deep link (https, or a custom
+ * scheme registered as a redirect URI on the calling application). For every
+ * other type the client renders from `type` + entity, and `title` / `message` /
+ * `data` are accepted but discarded, as they always were.
+ *
+ * `system` notifications share the duplicate guard (recipient, actor, type,
+ * entityId): use a caller-unique `entityId` (a job id) for each distinct event.
+ */
+export const createOxyNotificationRequestSchema = z
+    .object({
+    recipientId: z.string().min(1),
+    actorId: z.string().min(1),
+    type: z.enum(OXY_NOTIFICATION_TYPES),
+    entityId: z.string().min(1),
+    entityType: z.enum(OXY_NOTIFICATION_ENTITY_TYPES),
+    title: z.string().trim().min(1).max(OXY_SYSTEM_NOTIFICATION_TITLE_MAX).optional(),
+    message: z.string().trim().min(1).max(OXY_SYSTEM_NOTIFICATION_MESSAGE_MAX).optional(),
+    url: z.string().trim().min(1).max(OXY_NOTIFICATION_URL_MAX).optional(),
+    data: z.record(z.string(), z.unknown()).optional(),
+})
+    .superRefine((value, context) => {
+    if (value.type === 'system') {
+        if (value.actorId !== value.recipientId)
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['actorId'], message: 'a system notification is from the recipient\'s own account' });
+        if (!value.title)
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['title'], message: 'title is required for a system notification' });
+        if (!value.message)
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['message'], message: 'message is required for a system notification' });
+    }
+    else {
+        if (value.url !== undefined) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['url'], message: 'url is only stored for a system notification' });
+        }
+        if (value.entityType === 'app') {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['entityType'], message: "entityType 'app' is only valid for a system notification" });
+        }
+    }
+});