@godxjp/server-sdk 0.11.0 → 0.13.0

package/dist/http.d.ts

@@ -62,12 +62,17 @@ declare class GodxHttpError extends Error {
 declare function loadIssuer(issuerUrl: string, options?: HttpOptions): Promise<Issuer>;
 interface SsoClientConfig {
     issuer: string;
-    serviceSlug: string;
+    /**
+     * Catalog service slug, sent as `service_slug`. OMIT it for a mini app (`org_…`/`isv_…`
+     * client): the Platform routes to the mini-app lane only when `service_slug` is absent —
+     * the same rule as php-sdk's BrowserProfile/BrowserServer (`serviceSlug === null` → omitted).
+     */
+    serviceSlug?: string;
     clientId: string;
     /** Omit for a public (secretless) instance — PKCE alone then. */
     clientSecret?: string;
     redirectUri: string;
-    /** Token audience = the ServiceInstance slug (defaults to serviceSlug). */
+    /** Token audience = the ServiceInstance slug (defaults to serviceSlug; a mini app: its client_id). */
     audience?: string;
     /** Headers, deadline and fetch for every request this client makes. */
     http?: HttpOptions;
@@ -109,6 +114,7 @@ declare class GodxSsoClient {
     userinfo(accessToken: string): Promise<UserinfoResponse>;
     private tokenRequest;
     private postForm;
+    private serviceSlugField;
 }
 /**
  * Server-to-server reads with service credentials (X-Service-Slug/X-Service-Secret).

package/dist/http.js

@@ -5,7 +5,7 @@ import {
   createServiceApi,
   loadIssuer,
   platformFetch
-} from "./chunk-2N6BMNKT.js";
+} from "./chunk-DUFW6IQK.js";
 export {
   GodxHttpError,
   GodxSsoClient,

package/dist/notifications.d.ts

@@ -0,0 +1,269 @@
+import { HttpOptions, GodxHttpError } from './http.js';
+import 'jose';
+
+type NoticeLocale = "ja" | "en" | "vi";
+/** Copy in the locales Platform renders: `ja` required, `en`/`vi` optional. Plain text only. */
+interface LocalizedText {
+    readonly ja: string;
+    readonly en?: string | null;
+    readonly vi?: string | null;
+}
+/** Platform's closed categories; `service` is the one for a notice a service authors. */
+type NoticeCategory = "service" | "organization_invitation" | "access_request" | "service_provisioning" | "billing" | "security" | "operator";
+type NoticeActionStyle = "default" | "primary" | "danger";
+/** Whether a press carries a reason; Platform enforces it before calling the service. */
+type NoticeActionReason = "none" | "optional" | "required";
+/** One quick-action button (at most three on a notice). Only a service instance may offer them. */
+interface NoticeActionButton {
+    readonly id: string;
+    readonly label: LocalizedText;
+    readonly style?: NoticeActionStyle;
+    readonly reason?: NoticeActionReason;
+}
+/** Platform's wire body, in the shape both SDKs emit: only fields that were set. */
+interface NoticePayload {
+    recipients: string[];
+    category: NoticeCategory;
+    source_ref: string;
+    action_url: string;
+    title: Partial<Record<NoticeLocale, string>> & {
+        ja: string;
+    };
+    body: Partial<Record<NoticeLocale, string>> & {
+        ja: string;
+    };
+    kind?: string;
+    context?: Partial<Record<NoticeLocale, string>> & {
+        ja: string;
+    };
+    actions?: {
+        id: string;
+        label: Partial<Record<NoticeLocale, string>> & {
+            ja: string;
+        };
+        style: NoticeActionStyle;
+        reason: NoticeActionReason;
+    }[];
+    organization_id?: string;
+}
+/** A notice Platform would refuse (or silently drop part of); `field` is Laravel's dot-notation key. */
+declare class InvalidNoticeError extends Error {
+    readonly field: string;
+    constructor(field: string, reason: string);
+}
+interface NoticeFields {
+    readonly recipients: readonly string[];
+    readonly sourceRef: string;
+    readonly actionUrl: string;
+    readonly title: LocalizedText;
+    readonly body: LocalizedText;
+    readonly category: NoticeCategory;
+    readonly kind: string | null;
+    readonly context: LocalizedText | null;
+    readonly actions: readonly NoticeActionButton[];
+    readonly organizationId: string | null;
+}
+/**
+ * One notice, immutable: each `with…()` returns a new one, checked again.
+ *
+ * ```ts
+ * const notice = Notice.create({
+ *   recipients: [approverId],                          // Platform user ids, 1..100
+ *   sourceRef: `approval:task:${taskId}`,              // the dedup key: one row per ref per person
+ *   actionUrl: `${baseUrl}/requests/42`,               // absolute, under the instance base URL
+ *   title: { ja: "承認依頼", en: "Approval requested" },
+ *   body: { ja: "休暇申請 #42 が届きました。" },
+ * })
+ *   .withKind("approval")
+ *   .withActions(
+ *     { id: "approve", label: { ja: "承認", en: "Approve" }, style: "primary" },
+ *     { id: "reject", label: { ja: "却下", en: "Reject" }, style: "danger", reason: "required" },
+ *   );
+ * ```
+ *
+ * Every recipient must be a member of the organization with access to the service, or Platform
+ * refuses the WHOLE call (422) — checked there, not here. Sending the same `sourceRef` again
+ * rewrites that person's row and marks it unread, without a second email.
+ */
+declare class Notice implements NoticeFields {
+    readonly recipients: readonly string[];
+    readonly sourceRef: string;
+    readonly actionUrl: string;
+    readonly title: LocalizedText;
+    readonly body: LocalizedText;
+    readonly category: NoticeCategory;
+    readonly kind: string | null;
+    readonly context: LocalizedText | null;
+    readonly actions: readonly NoticeActionButton[];
+    readonly organizationId: string | null;
+    private constructor();
+    /** @throws InvalidNoticeError */
+    static create(input: {
+        recipients: readonly string[];
+        sourceRef: string;
+        actionUrl: string;
+        title: LocalizedText;
+        body: LocalizedText;
+    }): Notice;
+    /**
+     * Read a body in Platform's wire shape. Stricter than Platform on purpose: an unknown key or
+     * locale, which Platform would silently drop, is refused.
+     *
+     * @throws InvalidNoticeError
+     */
+    static fromPayload(payload: unknown): Notice;
+    withCategory(category: NoticeCategory): Notice;
+    /** One of the kinds the service declared in its manifest (`notifications`), so a person can turn it off. */
+    withKind(kind: string | null): Notice;
+    /** A short line placing the notice, printed under the email body (e.g. `WEB-123 · Website`). */
+    withContext(context: LocalizedText | null): Notice;
+    /** Replaces the quick actions (at most three). A notice with actions is never mirrored to Renraku. */
+    withActions(...actions: NoticeActionButton[]): Notice;
+    /** The CONSOLE organization id the notice is about — required for a deployment serving many organizations. */
+    forOrganization(consoleOrganizationId: string | null): Notice;
+    /**
+     * Platform's body, with only the fields that were set: an absent optional field and an empty one
+     * are not the same body to Platform's Idempotency-Key fingerprint.
+     */
+    toPayload(): NoticePayload;
+    private assertValid;
+}
+/** Why a notice was not delivered — the same strings as php-sdk's `NotificationFailure`. */
+type NotificationFailureReason = 
+/** No instance credential was configured, so nothing was sent. */
+"not_configured"
+/** 401. */
+ | "unauthenticated"
+/** 403: `notifications_api_enabled` is off (default) or the credential is wrong — Platform answers both alike. */
+ | "forbidden"
+/** 403 `ORGANIZATION_NOT_SERVED`: forOrganization() names one this instance does not serve. */
+ | "organization_not_served"
+/** 409: this Idempotency-Key was already used with another body. */
+ | "idempotency_conflict"
+/** 422: Platform refused the body — usually one recipient without access, which refuses the whole call. */
+ | "invalid" | "rate_limited"
+/** 5xx, a timeout or a network failure. The notice may or may not have been written. */
+ | "unavailable"
+/** A redirect, an unexpected status, or a success whose body is not Platform's shape. */
+ | "unexpected_response";
+/**
+ * A notice was not delivered. A {@link GodxHttpError}, so an existing catch keeps working; its
+ * `body` is always empty — like php-sdk, this client never reads an error body (Platform's have
+ * carried internal detail), only the `X-Godx-Error` code and `X-Request-Id`.
+ */
+declare class NotificationError extends GodxHttpError {
+    readonly reason: NotificationFailureReason;
+    readonly requestId: string | null;
+    constructor(reason: NotificationFailureReason, status?: number, requestId?: string | null, options?: {
+        cause?: unknown;
+    });
+    /**
+     * Whether sending again may succeed. Retry only with the SAME idempotency key and notice: an
+     * unavailable answer can follow a write that happened.
+     */
+    get retryable(): boolean;
+}
+/** Platform's answer: rows inserted, rows rewritten (same `source_ref`), people skipped (`preference_off`). */
+interface NoticeDelivery {
+    readonly created: readonly {
+        id: string;
+        user_id: string;
+    }[];
+    readonly updated: readonly {
+        id: string;
+        user_id: string;
+    }[];
+    readonly skipped: readonly {
+        user_id: string;
+        reason: string;
+    }[];
+}
+interface NotificationClientConfig {
+    issuer: string;
+    /** The INSTANCE slug (the token audience), never the client_id. */
+    serviceSlug: string;
+    /** The instance client_secret. */
+    serviceSecret: string;
+    /** Headers, deadline and fetch for every call. */
+    http?: HttpOptions;
+}
+interface NotificationClient {
+    /** Whether a credential is configured; without one, send() rejects with `not_configured`. */
+    readonly configured: boolean;
+    /**
+     * `idempotencyKey` (at most 191 characters): the same key and notice replay Platform's stored
+     * answer; the same key with another notice is `idempotency_conflict`.
+     */
+    send(notice: Notice, options?: {
+        idempotencyKey?: string;
+    }): Promise<NoticeDelivery>;
+}
+declare const NOTIFICATIONS_PATH = "/api/sso/service/notifications";
+/**
+ * The machine lane — the instance credential, gated by its capability `notifications_api_enabled`
+ * (default off). Redirects are never followed: a credential header must not reach another origin.
+ */
+declare function createNotificationClient(config: NotificationClientConfig): NotificationClient;
+/**
+ * The service's answer to a press. `done` and `already_done` SETTLE the notice: Platform remembers
+ * it and replays it on the next press without calling again — answer `already_done` only when the
+ * effect is confirmed.
+ */
+type NoticeActionState = "done" | "already_done" | "denied" | "invalid";
+interface NoticeActionResult {
+    readonly state: NoticeActionState;
+    /** One short line for the person, in the press's locale (Platform shows at most 500 characters). */
+    readonly message?: string | null;
+}
+/** One press, after the token was verified as Platform's notice-action token for a person. */
+interface NoticeAction {
+    /** Who pressed (`sub`) and in which organization (`organization_context_id`, the console id) — from the token, never the body. */
+    readonly principal: {
+        readonly subject: string;
+        readonly organization: string;
+        readonly clientId: string;
+        readonly scopes: readonly string[];
+    };
+    readonly sourceRef: string;
+    /** The button id. */
+    readonly action: string;
+    /** Null when none was written. */
+    readonly reason: string | null;
+    /** The language to answer `message` in. */
+    readonly locale: NoticeLocale | null;
+    readonly noticeId: string | null;
+}
+/**
+ * Platform decided NOTHING: it checked only that the person may still open the service and that the
+ * notice offered this button. The handler, as `press.principal` and under the service's own rules,
+ * finds the subject by `sourceRef` WITHIN `press.principal.organization`, answers `invalid` for an
+ * action it does not offer, re-checks the person's right (`denied`), and makes the change
+ * atomically. A thrown error is a 500, which the person sees as a failure; nothing is settled.
+ */
+type NoticeActionHandler = (press: NoticeAction) => NoticeActionResult | Promise<NoticeActionResult>;
+declare const NOTICE_ACTIONS_PATH = "/api/platform/v1/notice-actions";
+interface NoticeActionOptions {
+    issuer: string;
+    /** Your instance slug — the token's `aud`. */
+    audience: string;
+    handler: NoticeActionHandler;
+    /** Default `platform-notice-actions`. */
+    clientId?: string;
+    /** Default `notices.actions:execute`. */
+    scope?: string;
+    /** Headers, deadline and fetch for discovery and JWKS. */
+    http?: HttpOptions;
+}
+/**
+ * Answers Platform's `POST {base_url}/api/platform/v1/notice-actions` (Fetch API: Workers, Node 18+;
+ * Hono: `app.post(NOTICE_ACTIONS_PATH, (c) => handleNoticeAction(c.req.raw, options))`).
+ *
+ * The token is verified like php-sdk's `AuthenticateResource` does (RS256, `typ` at+jwt, exact
+ * issuer from discovery, `aud`, `exp`; else 401) — not with {@link verifyAccessToken}, because
+ * Platform mints this token without `organization_id`. Then it must be a PERSON's (`prn` user)
+ * from `clientId` carrying `scope`, else `403 {"error":"forbidden"}`; a malformed body is
+ * `422 {"state":"invalid"}`. The handler's answer is `{state, message?}`: 200, or 422 for `invalid`.
+ */
+declare function handleNoticeAction(request: Request, options: NoticeActionOptions): Promise<Response>;
+
+export { InvalidNoticeError, type LocalizedText, NOTICE_ACTIONS_PATH, NOTIFICATIONS_PATH, Notice, type NoticeAction, type NoticeActionButton, type NoticeActionHandler, type NoticeActionOptions, type NoticeActionReason, type NoticeActionResult, type NoticeActionState, type NoticeActionStyle, type NoticeCategory, type NoticeDelivery, type NoticeLocale, type NoticePayload, type NotificationClient, type NotificationClientConfig, NotificationError, type NotificationFailureReason, createNotificationClient, handleNoticeAction };