@oxyhq/contracts 0.25.0 → 0.27.0

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

@@ -0,0 +1,54 @@
+/**
+ * Version rule for the Oxy↔data-plane inference contracts.
+ *
+ * Oxy is the control plane; the inference data plane is a separate service.
+ * They are deployed independently, in different repositories, possibly in
+ * different languages.
+ * Every shape they exchange therefore carries its version IN THE PARSED DATA,
+ * never as a comment or an out-of-band assumption, so a producer running ahead
+ * of a consumer fails loudly at the parse instead of being silently reinterpreted.
+ *
+ * The rule, enforced by `src/__tests__/inference.compatibility.test.ts`:
+ *
+ *  - A schema carries `schemaVersion: z.literal(<n>)` **if and only if** it can
+ *    appear on the wire as a whole message — a request envelope, a stream event,
+ *    a catalogue descriptor, a ledger record, an error body.
+ *  - A schema that only ever appears EMBEDDED inside such a message (the
+ *    attribution block, one message part, one usage quantity, a data-retention
+ *    policy) carries no version of its own: it inherits the version of the
+ *    envelope it rides in. Versioning it separately would create two versions
+ *    that can disagree about one byte stream.
+ *  - A shape that is BOTH — `inferenceErrorSchema` is returned as an HTTP body
+ *    and also rides inside the stream's error event — keeps its own version.
+ *    The envelope's version then governs the envelope and the payload's governs
+ *    the payload, which is two versions of two things rather than two versions
+ *    of one.
+ *  - Every exported object schema in `src/inference/` must fall into exactly one
+ *    of those groups. The compatibility test holds both lists as exact
+ *    equalities, so a new shape that is in neither fails the build rather than
+ *    quietly shipping unversioned.
+ *
+ * A shape's own version is bumped when its meaning changes in a way a consumer
+ * pinned to the previous version would misread — a field removed, a field's
+ * units changed, a closed enum's member given a new meaning. Adding an OPTIONAL
+ * field is additive and does not bump it, because a consumer on the previous
+ * version parses the message correctly and simply does not read the new field.
+ *
+ * Decided in: docs/adr/0006-oxy-relay-boundary.md, docs/adr/0010-public-api-compatibility.md.
+ */
+/**
+ * Version of the contract SET as a whole — the value the control plane and the
+ * data plane exchange in a startup/health handshake to establish that they were built against
+ * compatible definitions before a single inference request is served.
+ *
+ * MAJOR is bumped when any individual shape's `schemaVersion` increments (at
+ * least one message is now read differently by the two sides); MINOR when a
+ * shape or an optional field is added; PATCH for documentation-only changes
+ * that leave every parsed byte identical.
+ *
+ * This constant is deliberately NOT embedded in the request envelope. Pinning a
+ * request to the version of the whole set would make an unrelated additive
+ * change to, say, the catalogue reject every in-flight inference request; the
+ * per-shape `schemaVersion` is what a message is validated against.
+ */
+export declare const INFERENCE_CONTRACT_VERSION = "1.0.0";

package/dist/types/oauth.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * The two `/auth/oauth/*` responses the browser hub's edge layer reads.
+ *
+ * They existed on the wire long before this file — `GET /auth/oauth/consent`
+ * and `POST /auth/oauth/authorize` are the surface `auth.oxy.so` has always
+ * driven with a bearer. What is new (issue #937 Phase 5) is a SECOND consumer
+ * that is not the SPA: the IdP's edge layer runs both calls server-side so the
+ * device-wide bearer never enters the browser's script context. A shape read by
+ * two independently deployed consumers is a contract, so it is written down
+ * once here and validated on both sides rather than transcribed into the edge.
+ *
+ * These are NOT the RFC 6749 token/userinfo responses. Those two speak flat
+ * OAuth/OIDC on the wire and are the one place in the API that does not use the
+ * `{ data }` envelope; these two are ordinary internal API responses that happen
+ * to be about OAuth.
+ */
+/**
+ * Server-authoritative answer to "must this user be shown a consent screen".
+ *
+ * Discriminated on `consentRequired` so the two arms cannot be confused by a
+ * consumer that reads `reason` first: `trusted`/`granted` are reasons NOT to
+ * ask, `new`/`scope_changed` are reasons to ask, and a flat object would let a
+ * typo in one produce a plausible value of the other.
+ *
+ *  - `trusted`       — the application is first-party/internal/system/official
+ *                      by the REGISTRY's verdict (`isTrustedApplication`), and
+ *                      the request names no scope over the user's own follow
+ *                      graph. Never inferred from a hostname.
+ *  - `granted`       — a prior `AppGrant` already covers every requested scope.
+ *  - `scope_changed` — a prior grant exists and is missing one.
+ *  - `new`           — no prior grant.
+ *
+ * `userConsentScopes` names the scopes that FORCED the screen, so the consent UI
+ * can say which one it is asking about. Present only on the `true` arm, and only
+ * when such a scope exists — a trusted app asked for one is still asked.
+ */
+export declare const oauthConsentDecisionSchema: z.ZodDiscriminatedUnion<"consentRequired", [z.ZodObject<{
+    consentRequired: z.ZodLiteral<false>;
+    reason: z.ZodEnum<["trusted", "granted"]>;
+}, "strip", z.ZodTypeAny, {
+    reason: "trusted" | "granted";
+    consentRequired: false;
+}, {
+    reason: "trusted" | "granted";
+    consentRequired: false;
+}>, z.ZodObject<{
+    consentRequired: z.ZodLiteral<true>;
+    reason: z.ZodEnum<["new", "scope_changed"]>;
+    userConsentScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    reason: "new" | "scope_changed";
+    consentRequired: true;
+    userConsentScopes?: string[] | undefined;
+}, {
+    reason: "new" | "scope_changed";
+    consentRequired: true;
+    userConsentScopes?: string[] | undefined;
+}>]>;
+/**
+ * A minted authorization code.
+ *
+ * `state` is echoed back as the caller sent it and is `null` when they sent
+ * none — never omitted, so a consumer cannot read "the server dropped my state"
+ * as "I sent none". `redirectUri` is echoed for the same reason the code is
+ * bound to it server-side: the caller must be able to see that the value the
+ * code was issued against is the one it registered.
+ */
+export declare const oauthAuthorizeCodeResponseSchema: z.ZodObject<{
+    code: z.ZodString;
+    state: z.ZodNullable<z.ZodString>;
+    redirectUri: z.ZodString;
+    expiresIn: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    state: string | null;
+    redirectUri: string;
+    expiresIn: number;
+}, {
+    code: string;
+    state: string | null;
+    redirectUri: string;
+    expiresIn: number;
+}>;
+export type OauthConsentDecision = z.infer<typeof oauthConsentDecisionSchema>;
+export type OauthAuthorizeCodeResponse = z.infer<typeof oauthAuthorizeCodeResponseSchema>;

package/dist/types/sessionStatus.d.ts

@@ -179,12 +179,12 @@ export declare const sessionStatusSchema: z.ZodObject<{
     openedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     status: string;
-    publicKey?: string | null | undefined;
-    userId?: string | null | undefined;
-    expiresAt?: string | undefined;
     sessionId?: string | null | undefined;
-    authorized?: boolean | undefined;
+    expiresAt?: string | undefined;
+    userId?: string | null | undefined;
+    publicKey?: string | null | undefined;
     sessionToken?: string | undefined;
+    authorized?: boolean | undefined;
     application?: {
         type: "system" | "first_party" | "third_party" | "internal";
         name: string;
@@ -204,12 +204,12 @@ export declare const sessionStatusSchema: z.ZodObject<{
     openedAt?: string | null | undefined;
 }, {
     status: string;
-    publicKey?: string | null | undefined;
-    userId?: string | null | undefined;
-    expiresAt?: string | undefined;
     sessionId?: string | null | undefined;
-    authorized?: boolean | undefined;
+    expiresAt?: string | undefined;
+    userId?: string | null | undefined;
+    publicKey?: string | null | undefined;
     sessionToken?: string | undefined;
+    authorized?: boolean | undefined;
     application?: {
         type: "system" | "first_party" | "third_party" | "internal";
         name: string;

package/dist/types/userResponse.d.ts

@@ -813,13 +813,13 @@ export declare const currentUserResponseSchema: z.ZodObject<{
         publicKey?: string | undefined;
         did?: string | undefined;
         verifiedDomains?: import("./identity").VerifiedDomain[] | undefined;
-        verified?: boolean | undefined;
-        email?: string | undefined;
         _id?: string | undefined;
+        email?: string | undefined;
         phone?: string | undefined;
         address?: string | undefined;
         birthday?: string | undefined;
         color?: string | null | undefined;
+        verified?: boolean | undefined;
         languages?: string[] | undefined;
         relationship?: UserRelationship | undefined;
         themePreference?: ThemePreference | undefined;
@@ -837,13 +837,13 @@ export declare const currentUserResponseSchema: z.ZodObject<{
         publicKey?: string | undefined;
         did?: string | undefined;
         verifiedDomains?: import("./identity").VerifiedDomain[] | undefined;
-        verified?: boolean | undefined;
-        email?: string | undefined;
         _id?: string | undefined;
+        email?: string | undefined;
         phone?: string | undefined;
         address?: string | undefined;
         birthday?: string | undefined;
         color?: string | null | undefined;
+        verified?: boolean | undefined;
         languages?: string[] | undefined;
         relationship?: UserRelationship | undefined;
         themePreference?: ThemePreference | undefined;
@@ -1107,6 +1107,7 @@ export declare const deviceLinkedSessionSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>>>;
 }, "strip", z.ZodTypeAny, {
     sessionId: string;
+    isCurrent?: boolean | undefined;
     user?: z.objectOutputType<{
         /** MongoDB ObjectId as a string. Present on `formatUserResponse` output. */
         id: z.ZodOptional<z.ZodString>;
@@ -1189,9 +1190,9 @@ export declare const deviceLinkedSessionSchema: z.ZodObject<{
          */
         themePreference: z.ZodOptional<z.ZodType<ThemePreference, z.ZodTypeDef, ThemePreference>>;
     }, z.ZodTypeAny, "passthrough"> | null | undefined;
-    isCurrent?: boolean | undefined;
 }, {
     sessionId: string;
+    isCurrent?: boolean | undefined;
     user?: z.objectInputType<{
         /** MongoDB ObjectId as a string. Present on `formatUserResponse` output. */
         id: z.ZodOptional<z.ZodString>;
@@ -1274,7 +1275,6 @@ export declare const deviceLinkedSessionSchema: z.ZodObject<{
          */
         themePreference: z.ZodOptional<z.ZodType<ThemePreference, z.ZodTypeDef, ThemePreference>>;
     }, z.ZodTypeAny, "passthrough"> | null | undefined;
-    isCurrent?: boolean | undefined;
 }>;
 export type DeviceLinkedSessionResponse = z.infer<typeof deviceLinkedSessionSchema>;
 /** Wire shape of `GET /session/device/sessions/:sessionId` (an array). */
@@ -1527,6 +1527,7 @@ export declare const deviceLinkedSessionsResponseSchema: z.ZodArray<z.ZodObject<
     }, z.ZodTypeAny, "passthrough">>>>;
 }, "strip", z.ZodTypeAny, {
     sessionId: string;
+    isCurrent?: boolean | undefined;
     user?: z.objectOutputType<{
         /** MongoDB ObjectId as a string. Present on `formatUserResponse` output. */
         id: z.ZodOptional<z.ZodString>;
@@ -1609,9 +1610,9 @@ export declare const deviceLinkedSessionsResponseSchema: z.ZodArray<z.ZodObject<
          */
         themePreference: z.ZodOptional<z.ZodType<ThemePreference, z.ZodTypeDef, ThemePreference>>;
     }, z.ZodTypeAny, "passthrough"> | null | undefined;
-    isCurrent?: boolean | undefined;
 }, {
     sessionId: string;
+    isCurrent?: boolean | undefined;
     user?: z.objectInputType<{
         /** MongoDB ObjectId as a string. Present on `formatUserResponse` output. */
         id: z.ZodOptional<z.ZodString>;
@@ -1694,7 +1695,6 @@ export declare const deviceLinkedSessionsResponseSchema: z.ZodArray<z.ZodObject<
          */
         themePreference: z.ZodOptional<z.ZodType<ThemePreference, z.ZodTypeDef, ThemePreference>>;
     }, z.ZodTypeAny, "passthrough"> | null | undefined;
-    isCurrent?: boolean | undefined;
 }>, "many">;
 export type DeviceLinkedSessionsResponseContract = z.infer<typeof deviceLinkedSessionsResponseSchema>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/contracts",
-  "version": "0.25.0",
+  "version": "0.27.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",