@oxy.so/contracts 5.2.0 → 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/dist/cjs/accountGraph.js +8 -5
  2. package/dist/cjs/accountName.js +20 -0
  3. package/dist/cjs/accountSubject.js +4 -2
  4. package/dist/cjs/client/accountGraph.js +2 -0
  5. package/dist/cjs/client/accountName.js +56 -0
  6. package/dist/cjs/client/index.js +12 -4
  7. package/dist/cjs/client/organizations.js +5 -4
  8. package/dist/cjs/index.js +31 -15
  9. package/dist/cjs/organizations.js +3 -7
  10. package/dist/cjs/sessionRevocation.js +89 -0
  11. package/dist/esm/accountGraph.js +9 -6
  12. package/dist/esm/accountName.js +12 -0
  13. package/dist/esm/accountSubject.js +4 -2
  14. package/dist/esm/client/accountGraph.js +2 -0
  15. package/dist/esm/client/accountName.js +51 -0
  16. package/dist/esm/client/index.js +1 -0
  17. package/dist/esm/client/organizations.js +5 -4
  18. package/dist/esm/index.js +2 -0
  19. package/dist/esm/organizations.js +4 -8
  20. package/dist/esm/sessionRevocation.js +86 -0
  21. package/dist/types/accountAccess.d.ts +5 -5
  22. package/dist/types/accountGraph.d.ts +12 -12
  23. package/dist/types/accountName.d.ts +5 -0
  24. package/dist/types/accountSubject.d.ts +3 -2
  25. package/dist/types/agency.d.ts +28 -28
  26. package/dist/types/client/accountGraph.d.ts +12 -6
  27. package/dist/types/client/accountName.d.ts +48 -0
  28. package/dist/types/client/deviceDirectory.d.ts +3 -3
  29. package/dist/types/client/index.d.ts +1 -0
  30. package/dist/types/client/organizations.d.ts +8 -7
  31. package/dist/types/client/safety.d.ts +2 -2
  32. package/dist/types/deviceDirectory.d.ts +33 -33
  33. package/dist/types/externalIdentity.d.ts +14 -14
  34. package/dist/types/index.d.ts +4 -0
  35. package/dist/types/inference/economics.d.ts +2 -2
  36. package/dist/types/inference/providerConnection.d.ts +4 -4
  37. package/dist/types/notifications.d.ts +4 -4
  38. package/dist/types/organizations.d.ts +41 -40
  39. package/dist/types/safety.d.ts +22 -22
  40. package/dist/types/sessionRevocation.d.ts +100 -0
  41. package/dist/types/stickers.d.ts +9 -9
  42. package/dist/types/userResponse.d.ts +42 -42
  43. package/package.json +1 -1
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Canonical contract for the session-revocation feed: oxy-api telling every
3
+ * connected Oxy backend that a session stopped being valid.
4
+ *
5
+ * WHY IT EXISTS. `@oxy.so/core/server` reuses a successful bearer validation on
6
+ * a backend for a short TTL, because an app backend cannot verify a user access
7
+ * token itself (HS256 under a secret only oxy-api holds) and asking Oxy on every
8
+ * request put ~300 ms on every authenticated route. A cache like that is only
9
+ * safe if it hears about revocations the moment they happen. This feed is how it
10
+ * hears: oxy-api announces every session it ends — logout, sign-out-all, device
11
+ * removal, an account switched away from, an admin or operator revocation, a
12
+ * credential change that ends sessions, account deletion or archive — and the
13
+ * SDK drops what it cached for that session or user.
14
+ *
15
+ * THE TRANSPORT IS THE SDK's. A backend opens no Redis client and wires nothing:
16
+ * `OxyServer` connects to the {@link OXY_SERVICE_EVENTS_NAMESPACE} Socket.IO
17
+ * namespace on oxy-api with its own service token, and uses its validation cache
18
+ * ONLY while that connection is live (connected, and a
19
+ * {@link OXY_SERVICE_EVENTS_HEARTBEAT_EVENT} seen within
20
+ * {@link OXY_SERVICE_EVENTS_STALE_AFTER_MS}). Disconnected, stale or never
21
+ * connected, it validates every request against Oxy. So a lost connection costs
22
+ * latency, never correctness.
23
+ *
24
+ * DELIVERY. A revocation is announced after the write that ended the session
25
+ * committed. Between oxy-api tasks it rides Valkey pub/sub, which is
26
+ * at-most-once; the heartbeat is what makes a silent loss of the path visible —
27
+ * a task emits it only while its own Valkey round trip works — so a consumer
28
+ * stops trusting its cache when the path stops working, instead of trusting it
29
+ * forever.
30
+ *
31
+ * PRIVACY — the payload carries ids and a timestamp only. Only Oxy's own
32
+ * (internal-tier) services may join the namespace, and even so nothing a
33
+ * consumer could render is ever placed on it.
34
+ *
35
+ * Platform-agnostic — zod only, no react/react-native/expo.
36
+ */
37
+ import { z } from 'zod';
38
+ /** The Socket.IO namespace on oxy-api that carries service events. */
39
+ export declare const OXY_SERVICE_EVENTS_NAMESPACE = "/service-events";
40
+ /** One session (or every session of one user) stopped being valid. */
41
+ export declare const OXY_SESSION_REVOKED_EVENT = "session:revoked";
42
+ /**
43
+ * Emitted on connect and then every {@link OXY_SERVICE_EVENTS_HEARTBEAT_MS}
44
+ * while the emitting oxy-api task can still hear revocations (its Valkey
45
+ * subscription round-trips). Carries `{ at }`, the task's epoch-ms clock.
46
+ */
47
+ export declare const OXY_SERVICE_EVENTS_HEARTBEAT_EVENT = "heartbeat";
48
+ /** How often a live oxy-api task sends {@link OXY_SERVICE_EVENTS_HEARTBEAT_EVENT}. */
49
+ export declare const OXY_SERVICE_EVENTS_HEARTBEAT_MS = 5000;
50
+ /**
51
+ * How long a consumer keeps trusting the feed after the last heartbeat. Past
52
+ * this the feed counts as down: every cached validation is dropped and nothing
53
+ * is cached until heartbeats resume.
54
+ */
55
+ export declare const OXY_SERVICE_EVENTS_STALE_AFTER_MS = 12000;
56
+ /**
57
+ * The `connect_error` message oxy-api answers a caller that may never join the
58
+ * namespace (not a service token, or not an internal-tier application). A
59
+ * consumer stops retrying quickly on it; any other refusal is retried.
60
+ */
61
+ export declare const OXY_SERVICE_EVENTS_FORBIDDEN = "service_events_forbidden";
62
+ /**
63
+ * A session revocation.
64
+ *
65
+ * - With `sessionId`: that one session ended. `userId` is the account it spoke
66
+ * as.
67
+ * - Without `sessionId`: every session of `userId` ended, or may have — the
68
+ * account was deleted or archived, or signed out everywhere. A consumer drops
69
+ * everything it holds for that account, including sessions it operated as a
70
+ * delegate.
71
+ *
72
+ * `at` is the publisher's epoch-ms clock: diagnostic only (propagation delay),
73
+ * never used for ordering — the event says "ask Oxy again", which is idempotent.
74
+ */
75
+ export declare const oxySessionRevocationEventSchema: z.ZodObject<{
76
+ /** The session that ended; absent for a revocation of every session of `userId`. */
77
+ sessionId: z.ZodOptional<z.ZodString>;
78
+ /** The account the session (or sessions) spoke as. */
79
+ userId: z.ZodString;
80
+ /** Publisher's epoch-ms timestamp. Diagnostic only. */
81
+ at: z.ZodNumber;
82
+ }, "strip", z.ZodTypeAny, {
83
+ at: number;
84
+ userId: string;
85
+ sessionId?: string | undefined;
86
+ }, {
87
+ at: number;
88
+ userId: string;
89
+ sessionId?: string | undefined;
90
+ }>;
91
+ export type OxySessionRevocationEvent = z.infer<typeof oxySessionRevocationEventSchema>;
92
+ /** The heartbeat payload. */
93
+ export declare const oxyServiceEventsHeartbeatSchema: z.ZodObject<{
94
+ at: z.ZodNumber;
95
+ }, "strip", z.ZodTypeAny, {
96
+ at: number;
97
+ }, {
98
+ at: number;
99
+ }>;
100
+ export type OxyServiceEventsHeartbeat = z.infer<typeof oxyServiceEventsHeartbeatSchema>;
@@ -245,9 +245,9 @@ export declare const stickerPackSummarySchema: z.ZodObject<{
245
245
  }>>;
246
246
  }, "strip", z.ZodTypeAny, {
247
247
  status: "draft" | "published" | "archived";
248
+ title: string;
248
249
  id: string;
249
250
  description: string | null;
250
- title: string;
251
251
  author: string | null;
252
252
  slug: string;
253
253
  publishedAt: string | null;
@@ -274,9 +274,9 @@ export declare const stickerPackSummarySchema: z.ZodObject<{
274
274
  } | null;
275
275
  }, {
276
276
  status: "draft" | "published" | "archived";
277
+ title: string;
277
278
  id: string;
278
279
  description: string | null;
279
- title: string;
280
280
  author: string | null;
281
281
  slug: string;
282
282
  publishedAt: string | null;
@@ -476,9 +476,9 @@ export declare const stickerPackSchema: z.ZodObject<{
476
476
  }>, "many">;
477
477
  }, "strip", z.ZodTypeAny, {
478
478
  status: "draft" | "published" | "archived";
479
+ title: string;
479
480
  id: string;
480
481
  description: string | null;
481
- title: string;
482
482
  author: string | null;
483
483
  slug: string;
484
484
  publishedAt: string | null;
@@ -525,9 +525,9 @@ export declare const stickerPackSchema: z.ZodObject<{
525
525
  }[];
526
526
  }, {
527
527
  status: "draft" | "published" | "archived";
528
+ title: string;
528
529
  id: string;
529
530
  description: string | null;
530
- title: string;
531
531
  author: string | null;
532
532
  slug: string;
533
533
  publishedAt: string | null;
@@ -750,9 +750,9 @@ export declare const installedStickerPackSchema: z.ZodObject<{
750
750
  installedAt: z.ZodString;
751
751
  }, "strip", z.ZodTypeAny, {
752
752
  status: "draft" | "published" | "archived";
753
+ title: string;
753
754
  id: string;
754
755
  description: string | null;
755
- title: string;
756
756
  author: string | null;
757
757
  slug: string;
758
758
  publishedAt: string | null;
@@ -800,9 +800,9 @@ export declare const installedStickerPackSchema: z.ZodObject<{
800
800
  installedAt: string;
801
801
  }, {
802
802
  status: "draft" | "published" | "archived";
803
+ title: string;
803
804
  id: string;
804
805
  description: string | null;
805
- title: string;
806
806
  author: string | null;
807
807
  slug: string;
808
808
  publishedAt: string | null;
@@ -1034,16 +1034,16 @@ export declare const createStickerPackRequestSchema: z.ZodObject<{
1034
1034
  export type CreateStickerPackRequest = z.infer<typeof createStickerPackRequestSchema>;
1035
1035
  /** PATCH /stickers/admin/packs/:packId */
1036
1036
  export declare const updateStickerPackRequestSchema: z.ZodObject<{
1037
- description: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
1038
1037
  title: z.ZodOptional<z.ZodString>;
1038
+ description: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
1039
1039
  author: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
1040
1040
  }, "strip", z.ZodTypeAny, {
1041
- description?: string | null | undefined;
1042
1041
  title?: string | undefined;
1042
+ description?: string | null | undefined;
1043
1043
  author?: string | null | undefined;
1044
1044
  }, {
1045
- description?: string | null | undefined;
1046
1045
  title?: string | undefined;
1046
+ description?: string | null | undefined;
1047
1047
  author?: string | null | undefined;
1048
1048
  }>;
1049
1049
  export type UpdateStickerPackRequest = z.infer<typeof updateStickerPackRequestSchema>;