@sublay/js 7.7.1 → 7.9.0

package/dist/index.d.mts

@@ -184,14 +184,182 @@ interface SignInResponse {
 }
 declare function signIn(client: SublayHttpClient, data: SignInProps): Promise<SignInResponse>;
 
+/**
+ * Every push event type — the full app-notification type set plus the chat
+ * `message` event (push-only). Mirrors the server's `PUSH_EVENT_TYPES` exactly
+ * (server `src/constants/push/pushEvents.ts`); these are the only names a
+ * `disabledTypes` set may contain.
+ */
+declare const PUSH_EVENT_TYPES: readonly ["entity-comment", "comment-reply", "entity-mention", "comment-mention", "entity-reaction", "comment-reaction", "entity-reaction-milestone-specific", "entity-reaction-milestone-total", "comment-reaction-milestone-specific", "comment-reaction-milestone-total", "new-follow", "connection-request", "connection-accepted", "space-membership-approved", "event-invite", "event-updated", "event-cancelled", "reputation-grant", "message"];
+type PushEventType = (typeof PUSH_EVENT_TYPES)[number];
+/**
+ * The four conversation-mute duration choices. Send the CHOICE, never a raw
+ * timestamp — the server resolves it and represents "forever" via the explicit
+ * `mutedForever` signal on the returned member. Mirrors the server's
+ * `MUTE_DURATIONS` (server `src/helpers/push/muteDuration.ts`).
+ */
+declare const MUTE_DURATIONS: readonly ["8h", "24h", "1w", "forever"];
+type MuteDuration = (typeof MUTE_DURATIONS)[number];
+/** Response of read/update notification preferences. */
+interface NotificationPreferences {
+    disabledTypes: PushEventType[];
+}
+/**
+ * A Web Push subscription in its SERIALIZED form — the JSON the server reads,
+ * not the live browser object.
+ *
+ * A `PushSubscription` straight from `PushManager.subscribe()` does NOT satisfy
+ * this type. It exposes its keys only through `getKey(name)`; there is no `keys`
+ * property to read, so it is not assignable here under strict TypeScript, and
+ * passing one through a cast sends a body the server rejects.
+ *
+ * To produce a value of this type:
+ *
+ * 1. **Serialize** the subscription with `subscription.toJSON()`.
+ * 2. **Confirm** `endpoint`, `keys.p256dh` and `keys.auth` are all present —
+ *    `PushSubscriptionJSON` types every one of them as optional, while the
+ *    server requires all three as non-empty strings and 400s otherwise.
+ *
+ * ```ts
+ * const json = subscription.toJSON();
+ * if (!json.endpoint || !json.keys?.p256dh || !json.keys?.auth) {
+ *   throw new Error("Incomplete Web Push subscription");
+ * }
+ * const webPushSubscription: WebPushSubscription = {
+ *   endpoint: json.endpoint,
+ *   keys: { p256dh: json.keys.p256dh, auth: json.keys.auth },
+ * };
+ * ```
+ *
+ * Mirrors the server's `webPushSubscriptionSchema`
+ * (server `src/v7/validation/push-notifications/push-notifications.schema.ts`).
+ */
+interface WebPushSubscription {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+/**
+ * Identifies one physical device. Mirrors the server's device-identifier body
+ * exactly (server `src/v7/validation/push-notifications/push-notifications.schema.ts`):
+ * a provider token for `ios`/`android`, a Web Push subscription for `web`. The
+ * union encodes the server's own cross-check — it rejects the same
+ * combinations the server's `superRefine` rejects.
+ *
+ * Passed to `auth.signOut` to unbind that device's push binding in the same
+ * transaction as the sign-out.
+ */
+type PushDeviceIdentifier = {
+    platform: "ios" | "android";
+    token: string;
+} | {
+    platform: "web";
+    subscription: WebPushSubscription;
+};
+
 interface SignOutProps {
     /**
      * Defaults to the SDK's stored refresh token (SDK-managed mode). Pass it
      * explicitly in host-managed mode, where the SDK holds no refresh token.
      */
     refreshToken?: string;
+    /**
+     * Optional. When supplied — and the project has the `push` bundle — the
+     * server deletes this user's push binding for that device in the SAME
+     * transaction as the token-family destroy: signing out unbinds the device's
+     * push, or nothing happens at all.
+     *
+     * **Needs a refresh token to have any effect.** The unbind is scoped to the
+     * `sub` of the refresh token, which is what stops one account removing
+     * another account's binding on a shared device — so with no token there is no
+     * user to scope it to and the server answers `204` before it ever looks at
+     * `pushDevice`. When none can be resolved the field is DROPPED from the
+     * request rather than sent into that silent no-op, the sign-out proceeds
+     * normally, and the returned `pushUnbindSkipped` says so. Watch for it in
+     * **host-managed mode**: such a client is built with `getToken` and no
+     * `initialTokens`, and its `setTokens` is inert, so it starts with no refresh
+     * token and can never acquire one. Pass `refreshToken` explicitly alongside
+     * `pushDevice` there.
+     *
+     * If the unbind fails the request fails (HTTP 500, code
+     * `auth/device-deregistration-failed` or `auth/sign-out-failed`) and NOTHING
+     * is committed — the session survives so the caller can retry, and this call
+     * rethrows WITHOUT clearing the SDK's local tokens, so the credential that
+     * retry needs is still there.
+     *
+     * That is the ONLY failure that leaves you signed in. Every other one — a
+     * `429` from the rate limiter or a quota gate, a `423`, a `503`, a `400` on
+     * the body, a dropped connection — never touched a push binding, so it
+     * clears the local tokens and RESOLVES: a user must always be able to sign
+     * out. See `UNBIND_FAILURE_CODES`.
+     *
+     * Omit it and the request is byte-identical to before this field existed.
+     */
+    pushDevice?: PushDeviceIdentifier;
 }
-declare function signOut(client: SublayHttpClient, data?: SignOutProps): Promise<void>;
+/**
+ * Why the unbind did not happen. Present only when `pushUnbindSkipped` is
+ * `true`, and it exists because THE TWO SKIPS ARE RECOVERED DIFFERENTLY — a
+ * caller that cannot tell them apart can only ever pick the wrong remedy for
+ * one of them:
+ *
+ * - `no-refresh-token` — this SDK never asked. Nothing was destroyed either:
+ *   with no token the server has no session to end, so the account, its
+ *   credential and its binding are all still there. **Retryable**: re-issue
+ *   the sign-out with an explicit `refreshToken` and the unbind happens.
+ * - `push-unbind-status-unknown` — the server was asked and could not answer.
+ *   The sign-out itself DID commit, so the credential that would have driven a
+ *   retry is gone; re-issuing achieves nothing. The binding clears when that
+ *   account next registers on this device, or when the server prunes the token
+ *   as undeliverable.
+ */
+type PushUnbindSkipReason = "no-refresh-token" | "push-unbind-status-unknown";
+interface SignOutResult {
+    /**
+     * `true` whenever a `pushDevice` was supplied and the unbind did NOT happen,
+     * so this device's push binding for that account may still be live. Either
+     * the SDK declined to ask (no refresh token to scope the unbind to) or the
+     * server could not answer whether a binding exists; `pushUnbindSkipReason`
+     * says which, and the two are recovered differently.
+     *
+     * `false` means NO SKIP WAS REPORTED — by this SDK or by the server. It is
+     * not a promise that no skip happened, and the difference is not academic:
+     * the server declines the unbind for several reasons it answers with a plain
+     * `204`, and every one of them reads `false` here.
+     *
+     *   - The refresh token is authentic but expired beyond the server's unbind
+     *     window (90 days past `exp`), so there is no subject to scope the unbind
+     *     to. Reachable from this SDK by passing an old `refreshToken` explicitly
+     *     alongside `pushDevice`.
+     *   - The refresh token is malformed or fails signature verification.
+     *   - The project has no `push` bundle, so no binding can exist.
+     *   - The unbind ran and matched zero rows — the binding was already gone, or
+     *     was never registered under this device key.
+     *
+     * The server logs each of those under its own reason; only the case where it
+     * could not determine whether a binding exists is reported in the response,
+     * because that is the one where the binding may still be LIVE and nobody
+     * looked. The rest either prove there was nothing to remove or leave a device
+     * key the server cannot attribute to a user, and neither gives the caller
+     * anything to act on beyond what it already knows.
+     *
+     * A request that failed short of an unbind attempt reads `false` too — a
+     * gate's `429` or `423`, a `503`, a `400`, a dropped connection. Those clear
+     * the local tokens and resolve rather than reject (see `UNBIND_FAILURE_CODES`
+     * for why), and none of them is a REPORTED skip; they are logged with a
+     * warning instead.
+     *
+     * The sign-out itself is unaffected by the flag in both directions: a user
+     * must always be able to sign out, so a skipped unbind never fails the call
+     * and never leaves the local tokens in place.
+     */
+    pushUnbindSkipped: boolean;
+    /** Set only when `pushUnbindSkipped` is `true`. See `PushUnbindSkipReason`. */
+    pushUnbindSkipReason?: PushUnbindSkipReason;
+}
+declare function signOut(client: SublayHttpClient, data?: SignOutProps): Promise<SignOutResult>;
 
 interface RequestNewAccessTokenProps {
     /** Defaults to the SDK's stored refresh token (SDK-managed mode). */
@@ -234,11 +402,33 @@ interface ChangePasswordProps {
     /** The user's current password (verified before the change). */
     password: string;
     newPassword: string;
+    /**
+     * Optional. The physical device making this call.
+     *
+     * A password change also deletes every push binding the user holds, so an
+     * intruder's device stops receiving notification content. Naming this device
+     * keeps ITS binding — nothing re-binds a device from its live session, so
+     * without this the handset the user just changed their password on goes
+     * quiet until the app cold-starts or switches accounts.
+     *
+     * Same value passed to `push.register` / `auth.signOut`. Omit it and every
+     * binding for the user goes, this device included.
+     */
+    pushDevice?: PushDeviceIdentifier;
 }
 interface ChangePasswordResponse {
     success: boolean;
     message: string;
 }
+/**
+ * Change the signed-in user's password.
+ *
+ * Ends every OTHER session for that user — every other device must sign in
+ * again with the new password — while the session making this call survives.
+ * The server identifies that session from the access token this request is
+ * already authenticated with, so nothing about the caller's session has to be
+ * sent.
+ */
 declare function changePassword(client: SublayHttpClient, data: ChangePasswordProps): Promise<ChangePasswordResponse>;
 
 interface SetPasswordProps {
@@ -831,6 +1021,91 @@ declare namespace Users {
   export { Users_checkUsernameAvailability as checkUsernameAvailability, Users_createBlock as createBlock, Users_createFollow as createFollow, Users_deleteBlock as deleteBlock, deleteFollow$1 as deleteFollow, Users_fetchBlockStatus as fetchBlockStatus, Users_fetchBlockedUsers as fetchBlockedUsers, Users_fetchConnectionStatus as fetchConnectionStatus, Users_fetchConnectionsByUserId as fetchConnectionsByUserId, Users_fetchConnectionsCountByUserId as fetchConnectionsCountByUserId, Users_fetchFollowStatus as fetchFollowStatus, Users_fetchFollowersByUserId as fetchFollowersByUserId, Users_fetchFollowersCountByUserId as fetchFollowersCountByUserId, Users_fetchFollowingByUserId as fetchFollowingByUserId, Users_fetchFollowingCountByUserId as fetchFollowingCountByUserId, Users_fetchUserByForeignId as fetchUserByForeignId, Users_fetchUserById as fetchUserById, Users_fetchUserByUsername as fetchUserByUsername, Users_fetchUserSuggestions as fetchUserSuggestions, Users_removeConnectionByUserId as removeConnectionByUserId, Users_requestConnection as requestConnection, Users_updateUser as updateUser };
 }
 
+/** The three grantable target kinds. Polymorphic — `targetId` carries no FK. */
+type ReputationGrantTargetType = "entity" | "comment" | "chat-message";
+/**
+ * Who created the grant. `"user"` is a debited transfer (reputation moved out
+ * of `senderId`'s bucket); `"app"` is a mint issued by the project itself with
+ * a null `senderId`. Persisted rather than inferred from `senderId`, which is
+ * also null for a transfer whose sender was later deleted.
+ */
+type ReputationGrantSourceType = "user" | "app";
+/**
+ * The "which item was rewarded" pair, as a both-or-neither union.
+ *
+ * Modelled as a two-branch union rather than two independent optional fields so
+ * a half-filled target — `{ targetType }` with no `targetId`, or the reverse —
+ * does not compile. The server answers that shape with
+ * `400 reputation-grant/invalid-body` on the write (a shared
+ * `bothOrNeitherTarget` refinement) and
+ * `400 reputation-grant/invalid-filter` on the list, so the union turns a
+ * guaranteed round trip into a red squiggle.
+ *
+ * The empty branch is `?: undefined`, NOT `?: null` — deliberately, and for the
+ * same reason `metadata` is not nullable: `grantBodyFields.targetType` is
+ * `.optional()` with no `.nullable()`, so an explicit `targetType: null` is
+ * rejected. Omit both keys to mean "no target".
+ *
+ * Building the pair conditionally needs one accommodation: an inline
+ * conditional spread of just these two keys widens both to `T | undefined` and
+ * then matches neither branch. Either branch the whole argument, or name this
+ * type on a helper and spread that:
+ *
+ * ```ts
+ * const target: ReputationGrantTargetFilter = item
+ *   ? { targetType: "entity", targetId: item.id }
+ *   : {};
+ * await listGrants(client, { ...base, ...target });
+ * ```
+ */
+type ReputationGrantTargetFilter = {
+    /** The kind of item rewarded. Requires `targetId` alongside it. */
+    targetType: ReputationGrantTargetType;
+    /** The rewarded item's id. Requires `targetType` alongside it. */
+    targetId: string;
+} | {
+    targetType?: undefined;
+    targetId?: undefined;
+};
+/**
+ * Per-item reputation-grant summary. Covers positive grants only — negative
+ * grants (app deductions) are invisible on every public read surface.
+ */
+interface GrantSummary {
+    /** Sum of positive grant amounts on the item. */
+    total: number;
+    /** Number of positive grants on the item. */
+    count: number;
+    /** The calling user's own summed positive grants on the item. */
+    viewerTotal: number;
+}
+/**
+ * A single reputation movement. Rows are append-only — nothing updates or
+ * soft-deletes them — so the table is the audit log behind every balance.
+ */
+interface ReputationGrant {
+    id: string;
+    sourceType: ReputationGrantSourceType;
+    /** Null for an app mint, and for a transfer whose sender was deleted. */
+    senderId: string | null;
+    /** Populated when the list is called with `include: "user"`. */
+    sender?: User | null;
+    recipientId: string;
+    /** Populated when the list is called with `include: "user"`. */
+    recipient?: User | null;
+    /** Non-zero. Negative only when `sourceType` is `"app"`. */
+    amount: number;
+    /** The bucket both legs moved in; null = the project-general bucket. */
+    spaceId: string | null;
+    /** Both null or both non-null. */
+    targetType: ReputationGrantTargetType | null;
+    targetId: string | null;
+    note: string | null;
+    metadata: Record<string, any> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
 type Mention = UserMention | SpaceMention;
 interface UserMention {
     type: "user";
@@ -1036,6 +1311,13 @@ interface Entity {
     nsfwEffective: boolean;
     topComment: TopComment | null;
     isSaved?: boolean;
+    /**
+     * Reputation-grant summary. Opt-in — present exactly when the read requested
+     * `include=grants`. Once requested the server always returns the object,
+     * zero-filled rather than omitted, on projects with no grants and on projects
+     * without the reputation bundle alike.
+     */
+    grants?: GrantSummary;
     isDraft: boolean | null;
     moderationStatus: "approved" | "removed" | null;
     moderatedAt: string | null;
@@ -1567,6 +1849,13 @@ interface Comment {
     reactionCounts: ReactionCounts;
     userReaction?: ReactionType | null;
     repliesCount: number;
+    /**
+     * Reputation-grant summary. Opt-in — present exactly when the read requested
+     * `include=grants`. Once requested the server always returns the object,
+     * zero-filled rather than omitted, on projects with no grants and on projects
+     * without the reputation bundle alike.
+     */
+    grants?: GrantSummary;
     metadata: Record<string, any>;
     createdAt: string;
     updatedAt: string;
@@ -2051,6 +2340,13 @@ interface ChatMessage {
     threadReplyCount: number;
     reactionCounts: Record<string, number>;
     userReactions: string[];
+    /**
+     * Reputation-grant summary. Opt-in — present exactly when the read requested
+     * `include=grants`. Once requested the server always returns the object,
+     * zero-filled rather than omitted, on projects with no grants and on projects
+     * without the reputation bundle alike.
+     */
+    grants?: GrantSummary;
     editedAt: string | null;
     userDeletedAt: string | null;
     moderationStatus: "approved" | "removed" | null;
@@ -2681,6 +2977,96 @@ declare namespace Reports {
   export { Reports_createReport as createReport, Reports_fetchModeratedReports as fetchModeratedReports };
 }
 
+interface CreateGrantBaseProps {
+    /** The user receiving the reputation. Cannot be the logged-in user. */
+    recipientId: string;
+    /**
+     * Positive integer. A user transfer can never mint (negatives) nor be a
+     * no-op (zero) — minting is service-key-only and lives in `@sublay/node`.
+     */
+    amount: number;
+    /** The bucket both legs move in. Omitted/null = the project-general bucket. */
+    spaceId?: string | null;
+    /**
+     * Free-text reason. Trimmed and capped at 2000 characters server-side.
+     * Genuinely nullable — an explicit `null` is accepted and means "no note".
+     */
+    note?: string | null;
+    /**
+     * Arbitrary JSON, capped at 1 MB server-side.
+     *
+     * NOT nullable — deliberately asymmetric with `note` directly above, not a
+     * typo. The server's shared `metadataSchema` is `z.record(...).optional()`
+     * with no `.nullable()`, so an explicit `metadata: null` is rejected with
+     * `400 reputation-grant/invalid-body`. Omit the key to mean "no metadata".
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * `targetType` and `targetId` are supplied together or not at all — the
+ * both-or-neither pair is carried by {@link ReputationGrantTargetFilter}, which
+ * makes the half-filled shape a compile error instead of a
+ * `400 reputation-grant/invalid-body`.
+ */
+type CreateGrantProps = CreateGrantBaseProps & ReputationGrantTargetFilter;
+/**
+ * Transfers reputation from the logged-in user to another user — a **debited
+ * transfer**: the amount leaves the sender's bucket and lands in the
+ * recipient's bucket in the same space. Nothing is created.
+ *
+ * There is no actor field: the sender is always the user the token belongs to.
+ * Naming somebody else as the sender requires a service key, which this SDK
+ * never holds.
+ */
+declare function createGrant(client: SublayHttpClient, data: CreateGrantProps): Promise<ReputationGrant>;
+
+interface ListGrantsBaseProps extends SpaceReputationContextParams {
+    page?: number;
+    limit?: number;
+    /** What this user received. */
+    recipientId?: string;
+    /** What this user sent. */
+    senderId?: string;
+    /** Associations to expand. Only `"user"` is supported (hydrates both parties). */
+    include?: string;
+}
+/**
+ * The third filter shape — "who rewarded this item" — is the
+ * {@link ReputationGrantTargetFilter} pair, so a half-filled target is a
+ * compile error rather than a `400 reputation-grant/invalid-filter`.
+ *
+ * Mutual exclusivity between the three shapes is NOT expressed in the type: a
+ * three-way exclusive union would multiply out across every pagination and
+ * space-reputation field and make the props unreadable, for a rule the server
+ * reports clearly. Only the both-or-neither pairing is typed.
+ */
+type ListGrantsProps = ListGrantsBaseProps & ReputationGrantTargetFilter;
+/**
+ * The `summary` block rides alongside the page envelope, and only on the
+ * target filter shape.
+ */
+interface ListGrantsResponse extends PaginatedResponse<ReputationGrant> {
+    summary?: GrantSummary;
+}
+/**
+ * Lists reputation grants.
+ *
+ * Exactly one filter shape per request — `recipientId`, `senderId`, or
+ * `targetType` + `targetId`. Supplying none or combining two is a `400`; the
+ * shapes are not AND-ed, which is what keeps the `summary` block reconcilable
+ * with the rows beneath it.
+ *
+ * Only positive grants are ever returned. Negative grants are app moderation
+ * deductions and are unreadable from every public surface.
+ */
+declare function listGrants(client: SublayHttpClient, data: ListGrantsProps): Promise<ListGrantsResponse>;
+
+declare const Reputation_createGrant: typeof createGrant;
+declare const Reputation_listGrants: typeof listGrants;
+declare namespace Reputation {
+  export { Reputation_createGrant as createGrant, Reputation_listGrants as listGrants };
+}
+
 interface SearchContentProps extends SpaceReputationContextParams {
     query: string;
     sourceTypes?: ("entity" | "comment" | "message")[];
@@ -3133,7 +3519,11 @@ interface ListMessagesProps extends SpaceReputationContextParams {
     /** Page size (default 50, max 100). */
     limit?: number;
     sort?: "asc" | "desc";
-    /** Comma-separated associations to populate, e.g. "files". */
+    /**
+     * Comma-separated associations to populate: `"files"` (message
+     * attachments) and `"grants"` (the reputation-grant summary). Combine
+     * them as `"files,grants"` — the server splits and trims this itself.
+     */
     include?: string;
     /** Optional filters, e.g. `{ hasReplies: true }`. */
     filters?: MessageFilters;
@@ -3173,6 +3563,11 @@ declare function sendMessage(client: SublayHttpClient, data: SendMessageProps):
 interface GetMessageProps extends SpaceReputationContextParams {
     conversationId: string;
     messageId: string;
+    /**
+     * Comma-separated associations to populate. Only `"grants"` is supported
+     * here — it attaches the message's reputation-grant summary.
+     */
+    include?: string;
 }
 declare function getMessage(client: SublayHttpClient, data: GetMessageProps): Promise<ChatMessage>;
 
@@ -3244,27 +3639,6 @@ declare function markAsRead(client: SublayHttpClient, data: MarkAsReadProps): Pr
     message: string;
 }>;
 
-/**
- * Every push event type — the full app-notification type set plus the chat
- * `message` event (push-only). Mirrors the server's `PUSH_EVENT_TYPES` exactly
- * (server `src/constants/push/pushEvents.ts`); these are the only names a
- * `disabledTypes` set may contain.
- */
-declare const PUSH_EVENT_TYPES: readonly ["entity-comment", "comment-reply", "entity-mention", "comment-mention", "entity-reaction", "comment-reaction", "entity-reaction-milestone-specific", "entity-reaction-milestone-total", "comment-reaction-milestone-specific", "comment-reaction-milestone-total", "new-follow", "connection-request", "connection-accepted", "space-membership-approved", "event-invite", "event-updated", "event-cancelled", "message"];
-type PushEventType = (typeof PUSH_EVENT_TYPES)[number];
-/**
- * The four conversation-mute duration choices. Send the CHOICE, never a raw
- * timestamp — the server resolves it and represents "forever" via the explicit
- * `mutedForever` signal on the returned member. Mirrors the server's
- * `MUTE_DURATIONS` (server `src/helpers/push/muteDuration.ts`).
- */
-declare const MUTE_DURATIONS: readonly ["8h", "24h", "1w", "forever"];
-type MuteDuration = (typeof MUTE_DURATIONS)[number];
-/** Response of read/update notification preferences. */
-interface NotificationPreferences {
-    disabledTypes: PushEventType[];
-}
-
 interface MuteConversationProps {
     conversationId: string;
     /**
@@ -3403,6 +3777,29 @@ interface WorkspaceInvitation {
 interface WorkspaceRosterReason {
     type: "owner" | "member" | "ancestor-owner" | "reach-holder" | "descendant-member";
     rank?: number;
+    /**
+     * The SAME ladder position, expressed as an offset from the CALLER: `1` = one
+     * rung below you, `0` = your peer, `-3` = three rungs above you. The caller's
+     * own anchor is their member row on this workspace if they hold one, and apex
+     * (one step above rank 0) if they do not — so a rank-0 member reads back as
+     * `relativeRank: 1` for an owner.
+     *
+     * Authority-bearing and fenced WITH `rank`, never beside it: it is `rank`
+     * minus a number the caller already knows, so leaking it leaks `rank` exactly.
+     *
+     * Present on same-node `member` reasons only. `descendant-member` entries
+     * carry `rank` but NEVER `relativeRank` — rank is per-workspace, so an offset
+     * measured against your standing on THIS node would be arithmetic across two
+     * different ladders. Use their absolute `rank` there.
+     *
+     * Note the deliberate asymmetry with the fence described above: the FENCE is
+     * per node (a descendant row may or may not carry `rank` depending on your
+     * standing there), but PRESENCE of `relativeRank` is not — it is absent on
+     * every `descendant-member` row, unconditionally, however much authority you
+     * hold. A field that appears and disappears by who is asking is worse to
+     * consume than one that is uniformly absent.
+     */
+    relativeRank?: number;
     capabilities?: WorkspaceCapability[];
     permissions?: string[];
     title?: string | null;
@@ -3442,6 +3839,13 @@ interface WorkspaceMemberStanding {
     capabilities?: WorkspaceCapability[];
     permissions?: string[];
     rank?: number | null;
+    /**
+     * `rank` expressed as an offset from the CALLER (negative = senior to you).
+     * `null` exactly when `rank` is `null` — a target with no direct member row
+     * here sits outside the ladder and has no position to measure. Fenced with
+     * `rank`: absent (not null) for a caller who may not see it.
+     */
+    relativeRank?: number | null;
     title: string | null;
     metadata: Record<string, any>;
 }
@@ -3514,7 +3918,11 @@ interface FetchManyWorkspacesProps {
 }
 /**
  * List the bearer-token user's direct-membership + owned workspaces. The actor
- * is derived from the token — no `userId` is sent.
+ * is derived from the token — no actor field is sent.
+ *
+ * ⚠️ Only the fields declared above are accepted. The workspaces endpoints
+ * refuse any undeclared top-level field with a 400 rather than ignoring it, so
+ * do not spread an unrelated object into `data`.
  */
 declare function fetchManyWorkspaces(client: SublayHttpClient, data?: FetchManyWorkspacesProps): Promise<PaginatedResponse<Workspace>>;
 
@@ -3525,7 +3933,7 @@ interface UpdateWorkspaceProps {
 }
 /**
  * Edit a workspace's name / metadata. Requires the `edit-workspace` capability
- * (or ownership). The actor is the bearer-token user — no `userId` is sent.
+ * (or ownership). The actor is the bearer-token user — no actor field is sent.
  */
 declare function updateWorkspace(client: SublayHttpClient, data: UpdateWorkspaceProps): Promise<Workspace>;
 
@@ -3537,7 +3945,7 @@ interface UpdateWorkspaceInheritFlagProps {
  * Flip whether capabilities held on an ancestor "reach" into this workspace.
  * Owner-only in both directions (own owner or an ancestor owner), and blocked
  * (403 `workspace/inherit-enforced`) when the project enforces its default.
- * The actor is the bearer-token user — no `userId` is sent.
+ * The actor is the bearer-token user — no actor field is sent.
  */
 declare function updateWorkspaceInheritFlag(client: SublayHttpClient, data: UpdateWorkspaceInheritFlagProps): Promise<Workspace>;
 
@@ -3549,8 +3957,8 @@ interface DeleteWorkspaceResponse {
 }
 /**
  * Owner-only delete (own owner or an ancestor owner). Cascades the whole
- * subtree transactionally. The actor is the bearer-token user — no `userId`
- * body is sent.
+ * subtree transactionally. The actor is the bearer-token user — no actor
+ * field is sent.
  */
 declare function deleteWorkspace(client: SublayHttpClient, data: DeleteWorkspaceProps): Promise<DeleteWorkspaceResponse>;
 
@@ -3563,7 +3971,7 @@ interface TransferWorkspaceOwnershipProps {
 }
 /**
  * Hand the workspace to a new owner. Owner-only (own owner or an ancestor
- * owner). The actor is the bearer-token user — no `userId` is sent;
+ * owner). The actor is the bearer-token user — no actor field is sent;
  * `newOwnerId` addresses the TARGET, not the actor.
  */
 declare function transferWorkspaceOwnership(client: SublayHttpClient, data: TransferWorkspaceOwnershipProps): Promise<Workspace>;
@@ -3577,6 +3985,11 @@ interface FetchWorkspaceMembersProps {
  * Unified roster read — one entry per distinct user, each with a `reasons`
  * array. Always returned in full (never paginated). With `countOnly=true` the
  * shape is `WorkspaceRosterCountsResponse` instead. Actor from the token.
+ *
+ * Same-node `member` reasons carry both rank coordinates: absolute `rank` and
+ * `relativeRank`, the offset from you (`1` = one rung below you, `-3` = three
+ * above). Both are fenced together and both are absent for a caller who does
+ * not operate people here. `descendant-member` reasons carry `rank` only.
  */
 declare function fetchWorkspaceMembers(client: SublayHttpClient, data: FetchWorkspaceMembersProps): Promise<WorkspaceRosterResponse | WorkspaceRosterCountsResponse>;
 
@@ -3586,7 +3999,11 @@ interface FetchWorkspaceMemberStandingProps {
 }
 /**
  * Read one user's resolved standing on a workspace (`reasons`, `capabilities`,
- * `permissions`, `rank`, `title`, `metadata`).
+ * `permissions`, `rank`, `relativeRank`, `title`, `metadata`).
+ *
+ * `relativeRank` is the target's `rank` as an offset from YOU (negative =
+ * senior to you), and is fenced with `rank`: both are absent, not null, for a
+ * caller who may not see the target's authority.
  */
 declare function fetchWorkspaceMemberStanding(client: SublayHttpClient, data: FetchWorkspaceMemberStandingProps): Promise<WorkspaceMemberStanding>;
 
@@ -3596,13 +4013,31 @@ interface UpdateWorkspaceMemberProps {
     capabilities?: WorkspaceCapability[];
     permissions?: string[];
     rank?: number;
+    /**
+     * `rank`'s relative twin: an offset from the ACTOR (`1` = one rung below me),
+     * resolved to an absolute rank at write time and stored absolute. Must be
+     * `>= 1`; mutually exclusive with `rank` (sending both is a 400). Both rank fields are also capped at `2147483647` (int4), and the RESOLVED sum is bounded too — an in-range anchor plus an in-range offset can still overflow, which is a 400 rather than a 500.
+     *
+     * The anchor is the actor's own rank if they hold a member row on this
+     * workspace, apex otherwise. A SNAPSHOT — frozen at write time, it does not
+     * follow the actor's own rank afterwards.
+     *
+     * Unlike invite, edit has NO default: omitting BOTH still means "rank
+     * unchanged", so editing someone's capabilities never moves them on the
+     * ladder.
+     */
+    relativeRank?: number;
     title?: string | null;
     metadata?: Record<string, any>;
 }
 /**
  * Edit a member's grant / profile. Powerful fields need `edit-member-access`
  * plus rank + no-escalation rules; cosmetic fields need only
- * `edit-member-profile`. No `userId` is sent — the actor comes from the token.
+ * `edit-member-profile`. No actor field is sent — the actor comes from the token.
+ *
+ * Rank moves in either coordinate — `rank` (absolute) or `relativeRank` (an
+ * offset from the actor) — never both. Omitting both leaves rank UNCHANGED;
+ * unlike invite, edit has no value default.
  */
 declare function updateWorkspaceMember(client: SublayHttpClient, data: UpdateWorkspaceMemberProps): Promise<WorkspaceMember>;
 
@@ -3613,7 +4048,7 @@ interface RemoveWorkspaceMemberProps {
 /**
  * Remove a member from this workspace. Requires the `remove-member` capability
  * and is rank-bounded. The workspace owner cannot be removed (409
- * `workspace/sole-owner`) — transfer ownership first. No `userId` body is sent;
+ * `workspace/sole-owner`) — transfer ownership first. No actor field is sent;
  * the actor comes from the token.
  */
 declare function removeWorkspaceMember(client: SublayHttpClient, data: RemoveWorkspaceMemberProps): Promise<void>;
@@ -3624,8 +4059,9 @@ interface LeaveWorkspaceProps {
 /**
  * The bearer-token user leaves this workspace — removes THEIR OWN direct
  * membership on THIS node only (owning a child is unaffected). An owner cannot
- * leave (409 `workspace/sole-owner`); transfer or delete first. No `userId` is
- * sent — the server derives the leaver from the token.
+ * leave (409 `workspace/sole-owner`) — transfer ownership or remove the
+ * workspace first. No actor field is sent; the server derives the leaver from
+ * the token.
  */
 declare function leaveWorkspace(client: SublayHttpClient, data: LeaveWorkspaceProps): Promise<void>;
 
@@ -3651,12 +4087,61 @@ interface CreateWorkspaceInviteProps {
     username?: string;
     capabilities?: WorkspaceCapability[];
     permissions?: string[];
-    rank: number;
+    /**
+     * The invited rank, ABSOLUTE — a position on this workspace's ladder (smaller
+     * = more senior). The escape hatch, and what tier-constant apps want, since
+     * they compute the number anyway.
+     *
+     * Optional, and mutually exclusive with `relativeRank` — sending both is a
+     * 400. Sending NEITHER defaults to `relativeRank: 1`, one rung below the
+     * inviter, which is well defined for every actor and can never fail the rank
+     * floor.
+     *
+     * ⚠️ That default is for a NEW invitation. Re-inviting a target who already
+     * has a live pending invite updates it in place, and there omitting both rank
+     * fields PRESERVES the stored rank instead of re-defaulting it. See the
+     * function doc below.
+     */
+    rank?: number;
+    /**
+     * The invited rank, RELATIVE to the inviter: `1` = one rung below me, `2` =
+     * two rungs below, and so on. The documented happy path — every governance
+     * rule about rank is relative, so this is what callers usually mean.
+     *
+     * Must be `>= 1` on a write. `0` would mean "a peer", which the assign rule
+     * forbids (you cannot clone your own authority), and a negative offset would
+     * mint someone senior to you; both are a 400. Both rank fields are also capped at `2147483647` (int4), and the RESOLVED sum is bounded too — an in-range anchor plus an in-range offset can still overflow, which is a 400 rather than a 500.
+     *
+     * The anchor is the inviter's OWN rank if they hold a member row on this
+     * workspace, and apex (one step above rank 0) if they do not — so an owner's
+     * `relativeRank: 1` lands on rank 0, while a rank-3 member's lands on rank 4.
+     *
+     * ⚠️ A SNAPSHOT, not a live link: the offset is resolved to an absolute rank
+     * once, at invite time, and frozen. It does not track the inviter's later
+     * promotions or demotions.
+     */
+    relativeRank?: number;
     title?: string | null;
 }
 /**
  * Create an invitation (requires the `invite` capability on the workspace). The
  * inviter is the bearer-token user.
+ *
+ * The invited rank comes in either coordinate — `rank` (absolute) or
+ * `relativeRank` (an offset from the inviter) — never both. Omitting both
+ * defaults to `relativeRank: 1`, one rung below the inviter, which is the
+ * documented happy path and can never fail the rank floor.
+ *
+ * ⚠️ This route doubles as an UPSERT, and the default above applies only to a
+ * NEW invitation. Re-inviting a target who already holds a live pending invite
+ * refreshes THAT invitation in place — same id, expiry reset — and on that
+ * branch an omitted grant field is PRESERVED, not re-defaulted or blanked:
+ * `rank`, `capabilities`, `permissions` and `title` all keep their stored
+ * values. A "Resend invitation" button that posts only the address therefore
+ * cannot silently re-rank the invitee to one below whoever clicked it. An
+ * explicit value still overwrites, and an explicit `relativeRank` re-resolves
+ * against the CURRENT caller. Full semantics:
+ * https://docs.sublay.io/api-reference/workspaces/invitations/create-invite
  */
 declare function createWorkspaceInvite(client: SublayHttpClient, data: CreateWorkspaceInviteProps): Promise<WorkspaceInvitation>;
 
@@ -3748,6 +4233,11 @@ interface FetchWorkspaceAuthorityProps {
  * Authority-as-a-service read — the bearer-token user's resolved standing
  * (`{ reasons, capabilities, permissions, rank }`) on the workspace. A
  * permission check is a one-line `.includes()` on the result.
+ *
+ * ⚠️ No `relativeRank` on this read. It is an offset from the caller, and here
+ * the caller IS the subject — so it could only ever be `0`. `rank` is the only
+ * rank coordinate this endpoint exposes. `relativeRank` is meaningful on the
+ * roster and member-standing reads, where the subject is somebody else.
  */
 declare function fetchWorkspaceAuthority(client: SublayHttpClient, data: FetchWorkspaceAuthorityProps): Promise<WorkspaceAuthority>;
 
@@ -3853,6 +4343,7 @@ declare class SublayClient {
     connections: BoundModule<typeof Connections>;
     appNotifications: BoundModule<typeof AppNotifications>;
     reports: BoundModule<typeof Reports>;
+    reputation: BoundModule<typeof Reputation>;
     search: BoundModule<typeof Search>;
     storage: BoundModule<typeof Storage>;
     oauth: BoundModule<typeof OAuth>;
@@ -3873,4 +4364,4 @@ declare class SublayClient {
     clearTokens(): void;
 }
 
-export { type AuthTokens, type BulkDeleteProps, type BulkDeleteResult, type ClientConfig, type DbFilter, type DbFilterOperator, type DeleteResult, MUTE_DURATIONS, type MuteConversationProps, type MuteConversationResponse, type MuteDuration, type NotificationPreferences, PUSH_EVENT_TYPES, type PaginatedResponse, type PaginationMetadata, type PushEventType, type RemoveWorkspaceMemberFromSubtreeResponse, type SkippedWorkspace, type SpaceReputationContextParams, type SpaceReputationUserParams, SublayClient, type TableAccessor, type TableQuery, type TableRow, type UpdateNotificationPreferencesProps, type UserSearchParams, type Workspace, type WorkspaceAuthority, type WorkspaceAuthorityReason, type WorkspaceAuthorityReasonDetail, type WorkspaceCapability, type WorkspaceInvitation, type WorkspaceInvitationStatus, type WorkspaceMember, type WorkspaceMemberStanding, type WorkspaceRosterCountsResponse, type WorkspaceRosterEntry, type WorkspaceRosterReason, type WorkspaceRosterResponse, type WorkspaceStandingUser };
+export { type AuthTokens, type BulkDeleteProps, type BulkDeleteResult, type ClientConfig, type CreateGrantProps, type DbFilter, type DbFilterOperator, type DeleteResult, type GrantSummary, type ListGrantsProps, type ListGrantsResponse, MUTE_DURATIONS, type MuteConversationProps, type MuteConversationResponse, type MuteDuration, type NotificationPreferences, PUSH_EVENT_TYPES, type PaginatedResponse, type PaginationMetadata, type PushDeviceIdentifier, type PushEventType, type PushUnbindSkipReason, type RemoveWorkspaceMemberFromSubtreeResponse, type ReputationGrant, type ReputationGrantSourceType, type ReputationGrantTargetFilter, type ReputationGrantTargetType, type SignOutResult, type SkippedWorkspace, type SpaceReputationContextParams, type SpaceReputationUserParams, SublayClient, type TableAccessor, type TableQuery, type TableRow, type UpdateNotificationPreferencesProps, type UserSearchParams, type WebPushSubscription, type Workspace, type WorkspaceAuthority, type WorkspaceAuthorityReason, type WorkspaceAuthorityReasonDetail, type WorkspaceCapability, type WorkspaceInvitation, type WorkspaceInvitationStatus, type WorkspaceMember, type WorkspaceMemberStanding, type WorkspaceRosterCountsResponse, type WorkspaceRosterEntry, type WorkspaceRosterReason, type WorkspaceRosterResponse, type WorkspaceStandingUser };