@fork-api/chat-sdk 0.1.177 → 0.1.180

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 (5) hide show
  1. package/dist/index.cjs +7 -7
  2. package/dist/index.d.cts +40 -6
  3. package/dist/index.d.ts +40 -6
  4. package/dist/index.js +7 -7
  5. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -63,7 +63,8 @@ interface ForkProviderBase {
63
63
  shared?: ForkSharedRegistry;
64
64
  }
65
65
  /**
66
- * User identity — provide EITHER userId (optionally with userHash) OR authUrl:
66
+ * User identity — provide EITHER userId (optionally with userHash or userJwt)
67
+ * OR authUrl:
67
68
  *
68
69
  * - `userId` alone: Client-asserted, no server verification (dev/testing only).
69
70
  * - `userId` + `userHash`: Host-brokered verified identity. Your backend
@@ -71,12 +72,37 @@ interface ForkProviderBase {
71
72
  * both as props. Fork never touches cookies or Web Storage for identity, so
72
73
  * this is the required mode for embedded/iframe contexts where third-party
73
74
  * cookies are blocked (e.g. app-store review environments).
74
- * - `authUrl`: URL on your backend that returns `{ userId, userHash }`.
75
- * The SDK calls this on mount (same-origin, cookies sent automatically).
76
- * Relies on the host's cookie session, so it does not work where the host
77
- * page's cookies are third-party — prefer the userHash prop mode there.
75
+ * - `userJwt`: OPTIONAL and ADDITIVE — it carries custom user attributes, it
76
+ * does not replace the identity you already send. Your backend signs HS256
77
+ * with a key DERIVED from your sk_ — `HMAC-SHA256(sk_, "fork-user-jwt-v1")`,
78
+ * never sk_ itself, which would let your own auth endpoint be used as a
79
+ * signing oracle. Payload: `{ sub: userId, attrs: { role, vertical, ... } }`
80
+ * with `audience: "fork"` and an `expiresIn` (both required, max 7 days).
81
+ * Everything in `attrs` becomes a custom user attribute visible in Fork
82
+ * admin. Because the claim sits inside the signature, an end user cannot
83
+ * forge it from devtools — which is why attributes ride here and not in a
84
+ * plain prop. Keep sending `userId` + `userHash` alongside it.
85
+ * - `authUrl`: URL on your backend that returns `{ userId, userHash }`, plus
86
+ * `userJwt` if you want attributes. The SDK calls it on mount (same-origin,
87
+ * cookies sent automatically). Relies on the host's cookie session, so it
88
+ * does not work where the host page's cookies are third-party — prefer the
89
+ * prop modes there.
78
90
  *
79
- * In either verified mode, if the user is also a Fork tenant operator (their
91
+ * `userHash` remains the universal credential and is NOT deprecated: it is what
92
+ * authenticates every request the SDK makes. `userJwt` is stamped on the
93
+ * provider's own calls, which is where attributes get recorded — one such call
94
+ * per mount is all it takes, since the server leaves stored attributes untouched
95
+ * on requests that carry no token.
96
+ *
97
+ * Adding attributes to an existing integration is therefore purely additive:
98
+ * return one more field from the endpoint you already have. Nothing you send
99
+ * today changes meaning, and rolling it back is deleting that field.
100
+ *
101
+ * Expiry is required and capped at 7 days; 24h is a reasonable choice. An
102
+ * expired token costs you attribute freshness, never access, because `userHash`
103
+ * is still carrying the identity.
104
+ *
105
+ * In any verified mode, if the user is also a Fork tenant operator (their
80
106
  * email matches a fork_users row with a user_roles entry on this tenant), the
81
107
  * SDK transparently enters admin mode and acts as their mapped end-user — set
82
108
  * the mapping in Fork's Team Settings → End user.
@@ -84,11 +110,13 @@ interface ForkProviderBase {
84
110
  type ForkProviderProps = ForkProviderBase & ({
85
111
  userId: string;
86
112
  userHash?: string;
113
+ userJwt?: string;
87
114
  authUrl?: never;
88
115
  } | {
89
116
  authUrl: string;
90
117
  userId?: never;
91
118
  userHash?: never;
119
+ userJwt?: never;
92
120
  });
93
121
  interface ForkBoundaryRegistration {
94
122
  id: string;
@@ -791,6 +819,12 @@ interface LoadManifestInput {
791
819
  userId: string;
792
820
  /** Optional userHash for HMAC verification. */
793
821
  userHash?: string;
822
+ /**
823
+ * Optional attribute-bearing token (see ForkProviderProps). Sent so the
824
+ * manifest fetch — which runs on every mount, for every user, not just
825
+ * operators — is what records the tenant's custom user attributes.
826
+ */
827
+ userJwt?: string;
794
828
  /** Authorized explicit container lookup, used for container-bound previews. */
795
829
  containerId?: string;
796
830
  /** Additional trusted headers, e.g. preview session headers. */
package/dist/index.d.ts CHANGED
@@ -63,7 +63,8 @@ interface ForkProviderBase {
63
63
  shared?: ForkSharedRegistry;
64
64
  }
65
65
  /**
66
- * User identity — provide EITHER userId (optionally with userHash) OR authUrl:
66
+ * User identity — provide EITHER userId (optionally with userHash or userJwt)
67
+ * OR authUrl:
67
68
  *
68
69
  * - `userId` alone: Client-asserted, no server verification (dev/testing only).
69
70
  * - `userId` + `userHash`: Host-brokered verified identity. Your backend
@@ -71,12 +72,37 @@ interface ForkProviderBase {
71
72
  * both as props. Fork never touches cookies or Web Storage for identity, so
72
73
  * this is the required mode for embedded/iframe contexts where third-party
73
74
  * cookies are blocked (e.g. app-store review environments).
74
- * - `authUrl`: URL on your backend that returns `{ userId, userHash }`.
75
- * The SDK calls this on mount (same-origin, cookies sent automatically).
76
- * Relies on the host's cookie session, so it does not work where the host
77
- * page's cookies are third-party — prefer the userHash prop mode there.
75
+ * - `userJwt`: OPTIONAL and ADDITIVE — it carries custom user attributes, it
76
+ * does not replace the identity you already send. Your backend signs HS256
77
+ * with a key DERIVED from your sk_ — `HMAC-SHA256(sk_, "fork-user-jwt-v1")`,
78
+ * never sk_ itself, which would let your own auth endpoint be used as a
79
+ * signing oracle. Payload: `{ sub: userId, attrs: { role, vertical, ... } }`
80
+ * with `audience: "fork"` and an `expiresIn` (both required, max 7 days).
81
+ * Everything in `attrs` becomes a custom user attribute visible in Fork
82
+ * admin. Because the claim sits inside the signature, an end user cannot
83
+ * forge it from devtools — which is why attributes ride here and not in a
84
+ * plain prop. Keep sending `userId` + `userHash` alongside it.
85
+ * - `authUrl`: URL on your backend that returns `{ userId, userHash }`, plus
86
+ * `userJwt` if you want attributes. The SDK calls it on mount (same-origin,
87
+ * cookies sent automatically). Relies on the host's cookie session, so it
88
+ * does not work where the host page's cookies are third-party — prefer the
89
+ * prop modes there.
78
90
  *
79
- * In either verified mode, if the user is also a Fork tenant operator (their
91
+ * `userHash` remains the universal credential and is NOT deprecated: it is what
92
+ * authenticates every request the SDK makes. `userJwt` is stamped on the
93
+ * provider's own calls, which is where attributes get recorded — one such call
94
+ * per mount is all it takes, since the server leaves stored attributes untouched
95
+ * on requests that carry no token.
96
+ *
97
+ * Adding attributes to an existing integration is therefore purely additive:
98
+ * return one more field from the endpoint you already have. Nothing you send
99
+ * today changes meaning, and rolling it back is deleting that field.
100
+ *
101
+ * Expiry is required and capped at 7 days; 24h is a reasonable choice. An
102
+ * expired token costs you attribute freshness, never access, because `userHash`
103
+ * is still carrying the identity.
104
+ *
105
+ * In any verified mode, if the user is also a Fork tenant operator (their
80
106
  * email matches a fork_users row with a user_roles entry on this tenant), the
81
107
  * SDK transparently enters admin mode and acts as their mapped end-user — set
82
108
  * the mapping in Fork's Team Settings → End user.
@@ -84,11 +110,13 @@ interface ForkProviderBase {
84
110
  type ForkProviderProps = ForkProviderBase & ({
85
111
  userId: string;
86
112
  userHash?: string;
113
+ userJwt?: string;
87
114
  authUrl?: never;
88
115
  } | {
89
116
  authUrl: string;
90
117
  userId?: never;
91
118
  userHash?: never;
119
+ userJwt?: never;
92
120
  });
93
121
  interface ForkBoundaryRegistration {
94
122
  id: string;
@@ -791,6 +819,12 @@ interface LoadManifestInput {
791
819
  userId: string;
792
820
  /** Optional userHash for HMAC verification. */
793
821
  userHash?: string;
822
+ /**
823
+ * Optional attribute-bearing token (see ForkProviderProps). Sent so the
824
+ * manifest fetch — which runs on every mount, for every user, not just
825
+ * operators — is what records the tenant's custom user attributes.
826
+ */
827
+ userJwt?: string;
794
828
  /** Authorized explicit container lookup, used for container-bound previews. */
795
829
  containerId?: string;
796
830
  /** Additional trusted headers, e.g. preview session headers. */