@orechio/platform-angular 0.2.0 → 0.6.0

package/types/orechio-platform-angular.d.ts

@@ -13,6 +13,12 @@ interface PlatformAngularAuthPaths {
     refresh: string;
     logout: string;
     me?: string;
+    /**
+     * Branch switch for an already-authenticated session. Optional: only BFFs that
+     * expose an authenticated switch endpoint set it, and `AuthClient.selectBranch`
+     * fails fast when it is absent rather than guessing a URL.
+     */
+    selectBranch?: string;
     /**
      * Unwraps the raw auth-endpoint response body into TUser. Defaults to the
      * identity function (response body IS the user object), matching Store's
@@ -109,6 +115,21 @@ declare class AuthClient<TUser extends SessionUser = SessionUser> {
      * which has no dedicated session-read endpoint and bootstraps via refresh).
      */
     initSession(): Observable<TUser>;
+    /**
+     * Asks the BFF to make `branchId` the current branch of the session that is
+     * already authenticated. No credentials are involved and none are re-sent: the
+     * browser proves nothing here beyond the session it already holds.
+     *
+     * `branchId` is a **requested target, never an authorization**. The BFF forwards
+     * it to the Platform, which re-reads the user's grants and refuses what is not
+     * granted — a rejection arrives as a failed request, and the session store is
+     * left exactly as it was, still on the previous branch.
+     *
+     * The store is updated only from the session the server returns, never
+     * optimistically from the requested id: the whole point of an explicit switch is
+     * that the server, not the client, decides which branch the user ends up in.
+     */
+    selectBranch(branchId: string): Observable<TUser>;
     refresh(): Observable<TUser>;
     /**
      * Clears the local session unconditionally — on success, on error, and on
@@ -123,6 +144,103 @@ declare class AuthClient<TUser extends SessionUser = SessionUser> {
     static ɵprov: i0.ɵɵInjectableDeclaration<AuthClient<any>>;
 }
 
+/**
+ * Control-flow code the Platform's auth contract returns (HTTP 409) when the
+ * authenticated user has access to more than one branch and none was chosen.
+ *
+ * It is deliberately NOT a failure: no session is created, no cookie is set,
+ * and the caller is expected to ask the user which branch to enter. Treating
+ * it as a generic error is the bug this constant exists to prevent.
+ */
+declare const BRANCH_SELECTION_REQUIRED_CODE = "auth.branch_selection_required";
+/**
+ * One selectable branch.
+ *
+ * `name` is optional because the current backend contract carries branch ids
+ * only — see `readBranchSelectionRequired`. Modelling it as optional now means
+ * the day the backend starts sending names, consumers get them without a
+ * breaking change to this type.
+ */
+interface BranchOption {
+    readonly id: string;
+    readonly name?: string | null;
+}
+/** Payload of a branch-selection-required response, normalized. */
+interface BranchSelectionRequired {
+    readonly branches: readonly BranchOption[];
+}
+/**
+ * Recognizes a branch-selection-required response and normalizes its payload,
+ * or returns `null` for anything else — so callers branch on a value instead of
+ * re-deriving the contract from status codes and body shapes.
+ *
+ * Reads three wire shapes, in this order of preference:
+ *
+ * 1. `branchOptions: [{ id, name }]` — the display metadata the Platform sends
+ *    alongside the ids. Preferred when present, because it is the only shape
+ *    that lets an operator tell the branches apart.
+ * 2. `branches: ["<guid>"]` — the original contract. Still authoritative for
+ *    selection, and still enough on its own.
+ * 3. `branches: [{ id, name }]` — tolerated since 0.3.0.
+ *
+ * Reading all three is what makes the rollout order irrelevant: a frontend on
+ * this version works against a backend that has the metadata and against one
+ * that does not, and neither side has to ship first.
+ *
+ * Entries without a usable id are dropped rather than rendered as blanks: an
+ * unselectable option in a selection list is worse than a shorter list.
+ */
+declare function readBranchSelectionRequired(error: unknown): BranchSelectionRequired | null;
+
+/**
+ * Explicit branch picker for the multi-branch login step.
+ *
+ * Deliberately narrow: it receives options, renders them, and emits the id the
+ * user actually chose. It does not call any backend, hold credentials, read
+ * tokens, touch storage, or know which product it is rendering inside — the
+ * flow around it belongs to the consumer, and the copy around it belongs to the
+ * consumer's login page.
+ *
+ * **It never picks for the user.** When the backend answers
+ * `auth.branch_selection_required` it has already refused to choose (no session
+ * is created); a selector that quietly defaulted to the first option would put
+ * the arbitrary choice back one layer up, in the place hardest to notice.
+ *
+ * Rendered as a radio group so the browser gives keyboard navigation, focus
+ * management, and screen-reader semantics for free — a list of buttons would
+ * need all three re-implemented, worse.
+ */
+declare class BranchSelector {
+    /** Options to choose from. An empty list renders the empty state, never a silent no-op. */
+    readonly branches: i0.InputSignal<readonly BranchOption[]>;
+    /** Blocks input while the consumer is completing the sign-in round-trip. */
+    readonly busy: i0.InputSignal<boolean>;
+    readonly legend: i0.InputSignal<string>;
+    readonly confirmLabel: i0.InputSignal<string>;
+    readonly emptyLabel: i0.InputSignal<string>;
+    /** Emits only in response to a user action. */
+    readonly selected: i0.OutputEmitterRef<string>;
+    protected chosen: string | null;
+    protected choose(id: string): void;
+    protected confirm(): void;
+    /**
+     * The name is the label whenever the contract carries one. The id fragment stays
+     * as secondary text rather than disappearing: the domain allows two branches to
+     * share a name, and when that happens the fragment is the only thing telling
+     * them apart.
+     *
+     * Without a name — an older backend, or metadata the server could not compose —
+     * the positional fallback keeps the list selectable. Two raw identifiers side by
+     * side are technically a choice and practically a coin flip, which is exactly
+     * why the name is preferred whenever it exists.
+     */
+    protected label(branch: BranchOption, index: number): string;
+    /** Fragment of the id, shown beside the label to disambiguate repeated names. */
+    protected fragment(branch: BranchOption): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BranchSelector, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<BranchSelector, "orechio-branch-selector", never, { "branches": { "alias": "branches"; "required": true; "isSignal": true; }; "busy": { "alias": "busy"; "required": false; "isSignal": true; }; "legend": { "alias": "legend"; "required": false; "isSignal": true; }; "confirmLabel": { "alias": "confirmLabel"; "required": false; "isSignal": true; }; "emptyLabel": { "alias": "emptyLabel"; "required": false; "isSignal": true; }; }, { "selected": "selected"; }, never, never, true, never>;
+}
+
 /**
  * Forces `withCredentials: true` on same-origin API requests, so the BFF's
  * HttpOnly session cookie is sent. Proven identically in both consumers.
@@ -271,5 +389,5 @@ interface PagedResult<T> {
     hasPrevious: boolean;
 }
 
-export { AuthClient, CapabilityDirective, PLATFORM_ANGULAR_CONFIG, SessionStore, credentialsInterceptor, hasCapability, normalizeProblemDetails, providePlatformAngularConfig, providePlatformAngularHttp, sessionExpiryInterceptor };
-export type { CapabilityMap, PagedResult, PlatformAngularAuthPaths, PlatformAngularConfig, ProblemDetails, SessionUser };
+export { AuthClient, BRANCH_SELECTION_REQUIRED_CODE, BranchSelector, CapabilityDirective, PLATFORM_ANGULAR_CONFIG, SessionStore, credentialsInterceptor, hasCapability, normalizeProblemDetails, providePlatformAngularConfig, providePlatformAngularHttp, readBranchSelectionRequired, sessionExpiryInterceptor };
+export type { BranchOption, BranchSelectionRequired, CapabilityMap, PagedResult, PlatformAngularAuthPaths, PlatformAngularConfig, ProblemDetails, SessionUser };

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Orechio
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.