@oxy.so/contracts 2.0.0 → 2.1.0

package/dist/types/federationInstanceFetch.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Wire contract for `POST /federation/instance-fetch/sign`: Oxy's INSTANCE
+ * actor signs one ActivityPub GET for a first-party service, so the service can
+ * read an instance running in authorized-fetch ("secure") mode without holding
+ * a key.
+ *
+ * The caller sends a URL, never a signing string: Oxy builds the string itself
+ * (`(request-target): get <path>`, `host`, `date`), the method is always GET
+ * and the key is always the instance actor's. The caller sends the returned
+ * headers, unchanged, on exactly that URL, within the few minutes remote
+ * servers accept a `Date` for. A redirect is a new URL and needs a new
+ * signature.
+ *
+ * Needs a service token whose application holds the privileged
+ * `federation:instance-fetch` scope.
+ *
+ * Platform-agnostic — zod only.
+ */
+import { z } from 'zod';
+/** The longest URL Oxy will sign (the same cap as its own safe fetch). */
+export declare const INSTANCE_FETCH_MAX_URL_LENGTH = 2048;
+export declare const instanceFetchSignRequestSchema: z.ZodObject<{
+    /** The absolute public `https://` URL the caller is about to GET. */
+    url: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    url: string;
+}, {
+    url: string;
+}>;
+export type InstanceFetchSignRequest = z.infer<typeof instanceFetchSignRequestSchema>;
+export declare const instanceFetchSignResponseSchema: z.ZodObject<{
+    /** The instance actor's key, e.g. `https://oxy.so/ap/users/instance#main-key`. */
+    keyId: z.ZodString;
+    /** Send all three on the GET, as they are. */
+    headers: z.ZodObject<{
+        Host: z.ZodString;
+        Date: z.ZodString;
+        Signature: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        Host: string;
+        Date: string;
+        Signature: string;
+    }, {
+        Host: string;
+        Date: string;
+        Signature: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    keyId: string;
+    headers: {
+        Host: string;
+        Date: string;
+        Signature: string;
+    };
+}, {
+    keyId: string;
+    headers: {
+        Host: string;
+        Date: string;
+        Signature: string;
+    };
+}>;
+export type InstanceFetchSignResponse = z.infer<typeof instanceFetchSignResponseSchema>;

package/dist/types/index.d.ts

@@ -104,4 +104,5 @@ export { inboxComposeRequestSchema, inboxDailyBriefRequestSchema, inboxNaturalSe
 export type { InboxComposeRequest, InboxDailyBriefRequest, InboxInferenceTextResponse, InboxNaturalSearchResponse, InboxSmartRepliesResponse, InboxThreadSummaryResponse, InboxInferenceStreamEvent, } from './inference/inbox';
 export * from './externalIdentity';
 export * from './linkedAccounts';
+export * from './federationInstanceFetch';
 export * from './notifications';

package/dist/types/inference/aliaModelRelease.d.ts

@@ -141,15 +141,15 @@ export declare const aliaReleaseSignatureSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     signature: string;
     signedAt: string;
+    keyId: string;
     algorithm: "ed25519";
     canonicalization: "jcs";
-    keyId: string;
 }, {
     signature: string;
     signedAt: string;
+    keyId: string;
     algorithm: "ed25519";
     canonicalization: "jcs";
-    keyId: string;
 }>;
 /**
  * A signed release of an `alia/*` model revision.
@@ -377,15 +377,15 @@ export declare const aliaModelReleaseManifestSchema: z.ZodEffects<z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         signature: string;
         signedAt: string;
+        keyId: string;
         algorithm: "ed25519";
         canonicalization: "jcs";
-        keyId: string;
     }, {
         signature: string;
         signedAt: string;
+        keyId: string;
         algorithm: "ed25519";
         canonicalization: "jcs";
-        keyId: string;
     }>, "many">;
 }, "strict", z.ZodTypeAny, {
     schemaVersion: 1;
@@ -417,9 +417,9 @@ export declare const aliaModelReleaseManifestSchema: z.ZodEffects<z.ZodObject<{
     signatures: {
         signature: string;
         signedAt: string;
+        keyId: string;
         algorithm: "ed25519";
         canonicalization: "jcs";
-        keyId: string;
     }[];
     license: {
         displayName: string;
@@ -471,9 +471,9 @@ export declare const aliaModelReleaseManifestSchema: z.ZodEffects<z.ZodObject<{
     signatures: {
         signature: string;
         signedAt: string;
+        keyId: string;
         algorithm: "ed25519";
         canonicalization: "jcs";
-        keyId: string;
     }[];
     license: {
         displayName: string;
@@ -525,9 +525,9 @@ export declare const aliaModelReleaseManifestSchema: z.ZodEffects<z.ZodObject<{
     signatures: {
         signature: string;
         signedAt: string;
+        keyId: string;
         algorithm: "ed25519";
         canonicalization: "jcs";
-        keyId: string;
     }[];
     license: {
         displayName: string;
@@ -579,9 +579,9 @@ export declare const aliaModelReleaseManifestSchema: z.ZodEffects<z.ZodObject<{
     signatures: {
         signature: string;
         signedAt: string;
+        keyId: string;
         algorithm: "ed25519";
         canonicalization: "jcs";
-        keyId: string;
     }[];
     license: {
         displayName: string;

package/dist/types/inference/modelDocumentation.d.ts

@@ -626,15 +626,15 @@ export declare const modelReleaseIngestionRequestSchema: z.ZodObject<{
         }, "strict", z.ZodTypeAny, {
             signature: string;
             signedAt: string;
+            keyId: string;
             algorithm: "ed25519";
             canonicalization: "jcs";
-            keyId: string;
         }, {
             signature: string;
             signedAt: string;
+            keyId: string;
             algorithm: "ed25519";
             canonicalization: "jcs";
-            keyId: string;
         }>, "many">;
     }, "strict", z.ZodTypeAny, {
         schemaVersion: 1;
@@ -666,9 +666,9 @@ export declare const modelReleaseIngestionRequestSchema: z.ZodObject<{
         signatures: {
             signature: string;
             signedAt: string;
+            keyId: string;
             algorithm: "ed25519";
             canonicalization: "jcs";
-            keyId: string;
         }[];
         license: {
             displayName: string;
@@ -720,9 +720,9 @@ export declare const modelReleaseIngestionRequestSchema: z.ZodObject<{
         signatures: {
             signature: string;
             signedAt: string;
+            keyId: string;
             algorithm: "ed25519";
             canonicalization: "jcs";
-            keyId: string;
         }[];
         license: {
             displayName: string;
@@ -774,9 +774,9 @@ export declare const modelReleaseIngestionRequestSchema: z.ZodObject<{
         signatures: {
             signature: string;
             signedAt: string;
+            keyId: string;
             algorithm: "ed25519";
             canonicalization: "jcs";
-            keyId: string;
         }[];
         license: {
             displayName: string;
@@ -828,9 +828,9 @@ export declare const modelReleaseIngestionRequestSchema: z.ZodObject<{
         signatures: {
             signature: string;
             signedAt: string;
+            keyId: string;
             algorithm: "ed25519";
             canonicalization: "jcs";
-            keyId: string;
         }[];
         license: {
             displayName: string;
@@ -1087,9 +1087,9 @@ export declare const modelReleaseIngestionRequestSchema: z.ZodObject<{
         signatures: {
             signature: string;
             signedAt: string;
+            keyId: string;
             algorithm: "ed25519";
             canonicalization: "jcs";
-            keyId: string;
         }[];
         license: {
             displayName: string;
@@ -1178,9 +1178,9 @@ export declare const modelReleaseIngestionRequestSchema: z.ZodObject<{
         signatures: {
             signature: string;
             signedAt: string;
+            keyId: string;
             algorithm: "ed25519";
             canonicalization: "jcs";
-            keyId: string;
         }[];
         license: {
             displayName: string;

package/dist/types/linkedAccounts.d.ts

@@ -339,3 +339,36 @@ export type ServiceLinkedAccountListResponse = z.infer<typeof serviceLinkedAccou
  */
 export declare const LINKED_ACCOUNT_CALLBACK_ERRORS: readonly ["access_denied", "verification_failed", "provider_unavailable"];
 export type LinkedAccountCallbackError = (typeof LINKED_ACCOUNT_CALLBACK_ERRORS)[number];
+/**
+ * Why `POST /linked-accounts/:network/start` refused, as `details.reason` on
+ * its 400 (`{ error: 'BAD_REQUEST', message, details: { reason } }`). The
+ * message is for logs; show the user a text chosen from the reason.
+ *
+ * - `instance_invalid`: the ActivityPub `instance` is not a server name.
+ * - `instance_unreachable`: the server does not resolve to a public address, or
+ *   could not be connected to.
+ * - `handle_unresolvable`: the atproto handle or DID does not resolve to an
+ *   account. The only reason that means "check what you typed".
+ * - `provider_rejected`: the other network answered and refused Oxy's
+ *   request — for atproto an authorization-server error such as
+ *   `invalid_client_metadata`; for a Mastodon-API server a refused app
+ *   registration (often: not a Mastodon-compatible server). Nothing the user
+ *   typed is wrong.
+ * - `provider_unavailable`: the other network could not be asked right now
+ *   (its OAuth metadata did not load, a 5xx, a timeout). Try again later.
+ *
+ * A refusal with no `details.reason` (a bad `returnTo`, a missing field) is a
+ * client bug, not something to show.
+ */
+export declare const LINKED_ACCOUNT_START_ERROR_REASONS: readonly ["instance_invalid", "instance_unreachable", "handle_unresolvable", "provider_rejected", "provider_unavailable"];
+export type LinkedAccountStartErrorReason = (typeof LINKED_ACCOUNT_START_ERROR_REASONS)[number];
+export declare const linkedAccountStartErrorReasonSchema: z.ZodEnum<["instance_invalid", "instance_unreachable", "handle_unresolvable", "provider_rejected", "provider_unavailable"]>;
+/** The `details` of a start refusal. */
+export declare const linkedAccountStartErrorDetailsSchema: z.ZodObject<{
+    reason: z.ZodEnum<["instance_invalid", "instance_unreachable", "handle_unresolvable", "provider_rejected", "provider_unavailable"]>;
+}, "strict", z.ZodTypeAny, {
+    reason: "provider_unavailable" | "instance_invalid" | "instance_unreachable" | "handle_unresolvable" | "provider_rejected";
+}, {
+    reason: "provider_unavailable" | "instance_invalid" | "instance_unreachable" | "handle_unresolvable" | "provider_rejected";
+}>;
+export type LinkedAccountStartErrorDetails = z.infer<typeof linkedAccountStartErrorDetailsSchema>;

package/dist/types/notifications.d.ts

@@ -91,3 +91,29 @@ export declare const createOxyNotificationRequestSchema: z.ZodEffects<z.ZodObjec
     title?: string | undefined;
 }>;
 export type CreateOxyNotificationRequest = z.infer<typeof createOxyNotificationRequestSchema>;
+/**
+ * Android notification channel a `system` notification is pushed on — a wire
+ * contract, because Android 8+ silently drops a push whose channel the app has
+ * not created. Created by the vault (Commons) before it registers its token.
+ */
+export declare const OXY_ACCOUNT_PUSH_CHANNEL = "account";
+/** Runtime type discriminator of the push that announces a `system` notification. */
+export declare const OXY_SYSTEM_NOTIFICATION_PUSH_TYPE = "oxy_system_notification";
+/**
+ * The ONLY data a `system` notification's push carries: its id. The title and
+ * message ride as the push's own title and body; the deep link does NOT travel,
+ * because a push payload is untrusted at the receiver. On a tap the vault
+ * re-reads the notification from Oxy by id (scoped to the signed-in recipient)
+ * and opens the `url` stored there.
+ */
+export declare const oxySystemNotificationPushDataSchema: z.ZodObject<{
+    type: z.ZodLiteral<"oxy_system_notification">;
+    notificationId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "oxy_system_notification";
+    notificationId: string;
+}, {
+    type: "oxy_system_notification";
+    notificationId: string;
+}>;
+export type OxySystemNotificationPushData = z.infer<typeof oxySystemNotificationPushDataSchema>;

package/package.json

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