@oxyhq/contracts 0.1.0 → 0.2.0

package/dist/types/sessionStatus.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Canonical contract for `GET /auth/session/status/:sessionToken`.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the cross-app device-flow
+ * session-status payload and the sanitized public application identity it
+ * embeds. The API validates its OUTPUT against these schemas; the auth app
+ * (consent UI) validates its INPUT against the same schemas. Because there is
+ * exactly one definition, the producer and the consumer cannot drift.
+ *
+ * The class of bug that motivated moving this into `@oxyhq/contracts`: the auth
+ * app's LOCAL `sessionStatusSchema` typed `sessionId` as a non-nullable
+ * `z.string().optional()`. The producer emits `sessionId: authorizedSessionId ||
+ * null`, so a PENDING session (not yet authorized) carries `sessionId: null` —
+ * `.optional()` permits `undefined`/missing but REJECTS `null`, so `safeParse`
+ * failed, the whole response collapsed to `null`, and the consent screen showed
+ * "Unable to identify the requesting application". Pinning the nullability in one
+ * shared place makes that drift impossible.
+ *
+ * Faithful to the producers:
+ *  - `packages/api/src/utils/serializeApplication.ts` `serializePublicApplication`
+ *    — the ONLY shape returned to an unauthenticated consent UI. Optional fields
+ *    (`description`, `icon`, `websiteUrl`, `developerName`) are OMITTED when
+ *    absent (never serialized as `null`), so they are `.optional()` — NOT
+ *    `.nullable()`. `type` is the `Application.type` enum.
+ *  - `packages/api/src/routes/auth.ts` `GET /session/status/:sessionToken` — the
+ *    inner object of the API's `{ data: ... }` success envelope. The handler
+ *    ALWAYS emits `status`, `authorized` (`status === 'authorized'`),
+ *    `sessionToken`, `expiresAt` (ISO string), and `application` (resolved object
+ *    OR `null`). It ALWAYS emits `sessionId` / `publicKey` / `userId`, each as a
+ *    string value OR `null` (`authorizedSessionId || null`, `authorizedBy ||
+ *    null`, `authorizedUserId?.toString() || null`).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Application `type` enum. Mirrors `APPLICATION_TYPES` in
+ * `packages/api/src/models/Application.ts` (`first_party` | `third_party` |
+ * `internal` | `system`).
+ */
+export declare const applicationTypeSchema: z.ZodEnum<["first_party", "third_party", "internal", "system"]>;
+export type ApplicationTypeContract = z.infer<typeof applicationTypeSchema>;
+/**
+ * The display-safe public identity of a requesting application, exactly as
+ * `serializePublicApplication` emits it. Returned by the API inside
+ * `GET /auth/session/status/:sessionToken` (device flow) and
+ * `GET /auth/oauth/client/:clientId` (OAuth code flow).
+ *
+ * Optional fields are `.optional()` (NOT `.nullable()`): the serializer OMITS
+ * `description` / `icon` / `websiteUrl` / `developerName` when the underlying
+ * value is absent — it never writes `null` for them. `developerName` is only
+ * attached for non-official apps when a name could be resolved.
+ */
+export declare const publicApplicationSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    websiteUrl: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<["first_party", "third_party", "internal", "system"]>;
+    isOfficial: z.ZodBoolean;
+    isInternal: z.ZodBoolean;
+    scopes: z.ZodArray<z.ZodString, "many">;
+    developerName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "first_party" | "third_party" | "internal" | "system";
+    id: string;
+    name: string;
+    isOfficial: boolean;
+    isInternal: boolean;
+    scopes: string[];
+    description?: string | undefined;
+    icon?: string | undefined;
+    websiteUrl?: string | undefined;
+    developerName?: string | undefined;
+}, {
+    type: "first_party" | "third_party" | "internal" | "system";
+    id: string;
+    name: string;
+    isOfficial: boolean;
+    isInternal: boolean;
+    scopes: string[];
+    description?: string | undefined;
+    icon?: string | undefined;
+    websiteUrl?: string | undefined;
+    developerName?: string | undefined;
+}>;
+export type PublicApplicationResponse = z.infer<typeof publicApplicationSchema>;
+/**
+ * The inner object of `GET /auth/session/status/:sessionToken` (inside the API's
+ * `{ data: ... }` envelope).
+ *
+ * `application` is the resolved {@link publicApplicationSchema} identity of the
+ * requesting application, or `null` when the bound app was hard-deleted / is no
+ * longer `active` (defensive — normally always present).
+ *
+ * `sessionId` / `publicKey` / `userId` are `.nullable().optional()`: the producer
+ * ALWAYS emits the key, with a string for an AUTHORIZED session or `null` for a
+ * PENDING one. `.nullable()` accepts the PENDING `null`; `.optional()` is belt-
+ * and-braces so a consumer is never broken by a future projection that drops the
+ * key. (`.optional()` alone would REJECT the PENDING `null` — that was the bug.)
+ *
+ * `authorized` / `sessionToken` / `expiresAt` are emitted unconditionally by the
+ * current producer and are never `null`, but stay `.optional()` so the contract
+ * tolerates leaner shapes from other producers of this same payload without a
+ * coordinated bump.
+ */
+export declare const sessionStatusSchema: z.ZodObject<{
+    status: z.ZodString;
+    authorized: z.ZodOptional<z.ZodBoolean>;
+    sessionToken: z.ZodOptional<z.ZodString>;
+    application: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        websiteUrl: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<["first_party", "third_party", "internal", "system"]>;
+        isOfficial: z.ZodBoolean;
+        isInternal: z.ZodBoolean;
+        scopes: z.ZodArray<z.ZodString, "many">;
+        developerName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "first_party" | "third_party" | "internal" | "system";
+        id: string;
+        name: string;
+        isOfficial: boolean;
+        isInternal: boolean;
+        scopes: string[];
+        description?: string | undefined;
+        icon?: string | undefined;
+        websiteUrl?: string | undefined;
+        developerName?: string | undefined;
+    }, {
+        type: "first_party" | "third_party" | "internal" | "system";
+        id: string;
+        name: string;
+        isOfficial: boolean;
+        isInternal: boolean;
+        scopes: string[];
+        description?: string | undefined;
+        icon?: string | undefined;
+        websiteUrl?: string | undefined;
+        developerName?: string | undefined;
+    }>>>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    publicKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    publicKey?: string | null | undefined;
+    expiresAt?: string | undefined;
+    sessionId?: string | null | undefined;
+    authorized?: boolean | undefined;
+    sessionToken?: string | undefined;
+    application?: {
+        type: "first_party" | "third_party" | "internal" | "system";
+        id: string;
+        name: string;
+        isOfficial: boolean;
+        isInternal: boolean;
+        scopes: string[];
+        description?: string | undefined;
+        icon?: string | undefined;
+        websiteUrl?: string | undefined;
+        developerName?: string | undefined;
+    } | null | undefined;
+    userId?: string | null | undefined;
+}, {
+    status: string;
+    publicKey?: string | null | undefined;
+    expiresAt?: string | undefined;
+    sessionId?: string | null | undefined;
+    authorized?: boolean | undefined;
+    sessionToken?: string | undefined;
+    application?: {
+        type: "first_party" | "third_party" | "internal" | "system";
+        id: string;
+        name: string;
+        isOfficial: boolean;
+        isInternal: boolean;
+        scopes: string[];
+        description?: string | undefined;
+        icon?: string | undefined;
+        websiteUrl?: string | undefined;
+        developerName?: string | undefined;
+    } | null | undefined;
+    userId?: string | null | undefined;
+}>;
+export type SessionStatusResponse = z.infer<typeof sessionStatusSchema>;