@oxy.so/contracts 1.4.0 → 1.5.0

package/dist/types/index.d.ts

@@ -105,3 +105,5 @@ export type { EmailContextAddress, EmailContextMailbox, EmailContextMessage, Ema
 export { inboxComposeRequestSchema, inboxDailyBriefRequestSchema, inboxNaturalSearchRequestSchema, inboxMessageInferenceParamsSchema, inboxInferenceTextResponseSchema, inboxNaturalSearchResponseSchema, inboxSmartRepliesResponseSchema, inboxThreadSummaryResponseSchema, inboxInferenceStreamEventSchema, } from './inference/inbox';
 export type { InboxComposeRequest, InboxDailyBriefRequest, InboxInferenceTextResponse, InboxNaturalSearchResponse, InboxSmartRepliesResponse, InboxThreadSummaryResponse, InboxInferenceStreamEvent, } from './inference/inbox';
 export * from './externalIdentity';
+export * from './linkedAccounts';
+export * from './notifications';

package/dist/types/linkedAccounts.d.ts

@@ -0,0 +1,341 @@
+/**
+ * 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 declare const LINKED_ACCOUNT_NETWORKS: readonly ["activitypub", "atproto"];
+export type LinkedAccountNetwork = (typeof LINKED_ACCOUNT_NETWORKS)[number];
+export declare const linkedAccountNetworkSchema: z.ZodEnum<["activitypub", "atproto"]>;
+/**
+ * `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 declare const startLinkedAccountRequestSchema: z.ZodObject<{
+    instance: z.ZodOptional<z.ZodString>;
+    handle: z.ZodOptional<z.ZodString>;
+    clientId: z.ZodString;
+    returnTo: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    clientId: string;
+    returnTo: string;
+    handle?: string | undefined;
+    instance?: string | undefined;
+}, {
+    clientId: string;
+    returnTo: string;
+    handle?: string | undefined;
+    instance?: string | undefined;
+}>;
+export type StartLinkedAccountRequest = z.infer<typeof startLinkedAccountRequestSchema>;
+export declare const startLinkedAccountResponseSchema: z.ZodObject<{
+    authorizeUrl: z.ZodString;
+    expiresAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    expiresAt: string;
+    authorizeUrl: string;
+}, {
+    expiresAt: string;
+    authorizeUrl: string;
+}>;
+export type StartLinkedAccountResponse = z.infer<typeof startLinkedAccountResponseSchema>;
+/**
+ * `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 declare const completeLinkedAccountRequestSchema: z.ZodObject<{
+    code: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+}, {
+    code: string;
+}>;
+export type CompleteLinkedAccountRequest = z.infer<typeof completeLinkedAccountRequestSchema>;
+/** One live linked account, as its owner sees it. */
+export declare const linkedAccountSchema: z.ZodObject<{
+    id: z.ZodString;
+    network: z.ZodEnum<["activitypub", "atproto"]>;
+    /** `username@domain` for ActivityPub; the DID for atproto. */
+    accountKey: z.ZodString;
+    /** ActivityPub actor id, or the DID for atproto. */
+    actorUri: z.ZodString;
+    handle: z.ZodString;
+    host: z.ZodString;
+    proofMethod: z.ZodLiteral<"oauth">;
+    verifiedAt: z.ZodString;
+    createdAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    createdAt: string;
+    verifiedAt: string;
+    handle: string;
+    network: "activitypub" | "atproto";
+    actorUri: string;
+    accountKey: string;
+    host: string;
+    proofMethod: "oauth";
+}, {
+    id: string;
+    createdAt: string;
+    verifiedAt: string;
+    handle: string;
+    network: "activitypub" | "atproto";
+    actorUri: string;
+    accountKey: string;
+    host: string;
+    proofMethod: "oauth";
+}>;
+export type LinkedAccount = z.infer<typeof linkedAccountSchema>;
+export declare const completeLinkedAccountResponseSchema: z.ZodObject<{
+    linkedAccount: z.ZodObject<{
+        id: z.ZodString;
+        network: z.ZodEnum<["activitypub", "atproto"]>;
+        /** `username@domain` for ActivityPub; the DID for atproto. */
+        accountKey: z.ZodString;
+        /** ActivityPub actor id, or the DID for atproto. */
+        actorUri: z.ZodString;
+        handle: z.ZodString;
+        host: z.ZodString;
+        proofMethod: z.ZodLiteral<"oauth">;
+        verifiedAt: z.ZodString;
+        createdAt: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+    }, {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+    }>;
+}, "strict", z.ZodTypeAny, {
+    linkedAccount: {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+    };
+}, {
+    linkedAccount: {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+    };
+}>;
+export type CompleteLinkedAccountResponse = z.infer<typeof completeLinkedAccountResponseSchema>;
+export declare const linkedAccountListResponseSchema: z.ZodObject<{
+    linkedAccounts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        network: z.ZodEnum<["activitypub", "atproto"]>;
+        /** `username@domain` for ActivityPub; the DID for atproto. */
+        accountKey: z.ZodString;
+        /** ActivityPub actor id, or the DID for atproto. */
+        actorUri: z.ZodString;
+        handle: z.ZodString;
+        host: z.ZodString;
+        proofMethod: z.ZodLiteral<"oauth">;
+        verifiedAt: z.ZodString;
+        createdAt: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+    }, {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    linkedAccounts: {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+    }[];
+}, {
+    linkedAccounts: {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+    }[];
+}>;
+export type LinkedAccountListResponse = z.infer<typeof linkedAccountListResponseSchema>;
+/**
+ * `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 declare const serviceLinkedAccountSchema: z.ZodObject<{
+    id: z.ZodString;
+    network: z.ZodEnum<["activitypub", "atproto"]>;
+    /** `username@domain` for ActivityPub; the DID for atproto. */
+    accountKey: z.ZodString;
+    /** ActivityPub actor id, or the DID for atproto. */
+    actorUri: z.ZodString;
+    handle: z.ZodString;
+    host: z.ZodString;
+    proofMethod: z.ZodLiteral<"oauth">;
+    verifiedAt: z.ZodString;
+    createdAt: z.ZodString;
+} & {
+    federatedUserId: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    createdAt: string;
+    verifiedAt: string;
+    handle: string;
+    network: "activitypub" | "atproto";
+    actorUri: string;
+    accountKey: string;
+    host: string;
+    proofMethod: "oauth";
+    federatedUserId: string | null;
+}, {
+    id: string;
+    createdAt: string;
+    verifiedAt: string;
+    handle: string;
+    network: "activitypub" | "atproto";
+    actorUri: string;
+    accountKey: string;
+    host: string;
+    proofMethod: "oauth";
+    federatedUserId: string | null;
+}>;
+export type ServiceLinkedAccount = z.infer<typeof serviceLinkedAccountSchema>;
+export declare const serviceLinkedAccountListResponseSchema: z.ZodObject<{
+    userId: z.ZodString;
+    linkedAccounts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        network: z.ZodEnum<["activitypub", "atproto"]>;
+        /** `username@domain` for ActivityPub; the DID for atproto. */
+        accountKey: z.ZodString;
+        /** ActivityPub actor id, or the DID for atproto. */
+        actorUri: z.ZodString;
+        handle: z.ZodString;
+        host: z.ZodString;
+        proofMethod: z.ZodLiteral<"oauth">;
+        verifiedAt: z.ZodString;
+        createdAt: z.ZodString;
+    } & {
+        federatedUserId: z.ZodNullable<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+        federatedUserId: string | null;
+    }, {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+        federatedUserId: string | null;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    userId: string;
+    linkedAccounts: {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+        federatedUserId: string | null;
+    }[];
+}, {
+    userId: string;
+    linkedAccounts: {
+        id: string;
+        createdAt: string;
+        verifiedAt: string;
+        handle: string;
+        network: "activitypub" | "atproto";
+        actorUri: string;
+        accountKey: string;
+        host: string;
+        proofMethod: "oauth";
+        federatedUserId: string | null;
+    }[];
+}>;
+export type ServiceLinkedAccountListResponse = z.infer<typeof serviceLinkedAccountListResponseSchema>;
+/**
+ * Error codes the callback appends as `?link_error=<code>` to `returnTo`. An
+ * account already linked to someone else is reported by `/complete` (409).
+ */
+export declare const LINKED_ACCOUNT_CALLBACK_ERRORS: readonly ["access_denied", "verification_failed", "provider_unavailable"];
+export type LinkedAccountCallbackError = (typeof LINKED_ACCOUNT_CALLBACK_ERRORS)[number];

package/dist/types/notifications.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 declare const OXY_NOTIFICATION_TYPES: readonly ["like", "reply", "mention", "follow", "repost", "quote", "welcome", "system"];
+export type OxyNotificationType = (typeof OXY_NOTIFICATION_TYPES)[number];
+/**
+ * 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 declare const OXY_NOTIFICATION_ENTITY_TYPES: readonly ["post", "reply", "profile", "app"];
+export type OxyNotificationEntityType = (typeof OXY_NOTIFICATION_ENTITY_TYPES)[number];
+/** Length caps on the text a `system` notification carries (enforced by CHECKs too). */
+export declare const OXY_SYSTEM_NOTIFICATION_TITLE_MAX = 120;
+export declare const OXY_SYSTEM_NOTIFICATION_MESSAGE_MAX = 500;
+export declare 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 declare const createOxyNotificationRequestSchema: z.ZodEffects<z.ZodObject<{
+    recipientId: z.ZodString;
+    actorId: z.ZodString;
+    type: z.ZodEnum<["like", "reply", "mention", "follow", "repost", "quote", "welcome", "system"]>;
+    entityId: z.ZodString;
+    entityType: z.ZodEnum<["post", "reply", "profile", "app"]>;
+    title: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "system" | "like" | "reply" | "follow" | "mention" | "quote" | "repost" | "welcome";
+    recipientId: string;
+    actorId: string;
+    entityId: string;
+    entityType: "profile" | "reply" | "post" | "app";
+    message?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    url?: string | undefined;
+    title?: string | undefined;
+}, {
+    type: "system" | "like" | "reply" | "follow" | "mention" | "quote" | "repost" | "welcome";
+    recipientId: string;
+    actorId: string;
+    entityId: string;
+    entityType: "profile" | "reply" | "post" | "app";
+    message?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    url?: string | undefined;
+    title?: string | undefined;
+}>, {
+    type: "system" | "like" | "reply" | "follow" | "mention" | "quote" | "repost" | "welcome";
+    recipientId: string;
+    actorId: string;
+    entityId: string;
+    entityType: "profile" | "reply" | "post" | "app";
+    message?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    url?: string | undefined;
+    title?: string | undefined;
+}, {
+    type: "system" | "like" | "reply" | "follow" | "mention" | "quote" | "repost" | "welcome";
+    recipientId: string;
+    actorId: string;
+    entityId: string;
+    entityType: "profile" | "reply" | "post" | "app";
+    message?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    url?: string | undefined;
+    title?: string | undefined;
+}>;
+export type CreateOxyNotificationRequest = z.infer<typeof createOxyNotificationRequestSchema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/contracts",
-  "version": "1.4.0",
+  "version": "1.5.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",