@globalpayments-private/gpds-pattern-web 0.0.0-stage → 0.1.0-pr.7.gdcb74cd

package/dist/types/providers/auth-provider.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Provider contracts for the GP pattern library.
+ *
+ * A pattern owns the *workflow* — which step comes next, what is in flight,
+ * what the user is told when something fails. It owns no SDK code and knows no
+ * identity platform. The seam between the two is a Provider contract: the
+ * consumer brings their own backend SDK (Okta, Auth0, Cognito, Ping, GCP API
+ * Gateway, Azure APIM, …) and writes a thin adapter against the interface
+ * below.
+ *
+ * See `docs/adr/0002-provider-driven-patterns.md` for why the workflow lives
+ * inside the pattern rather than in the host application.
+ */
+/** Opaque session handle returned by the identity platform on success. */
+export type UdsSession = unknown;
+/**
+ * Closed set of failure reasons a pattern knows how to explain to a user.
+ *
+ * It is deliberately small and generic: the pattern maps each code to approved,
+ * domain-neutral copy so that every GP product fails in the same words. An
+ * adapter that cannot classify a failure should return `unknown`.
+ */
+export type UdsAuthErrorCode = 'invalid_credentials' | 'invalid_identifier' | 'invalid_code' | 'code_expired' | 'account_locked' | 'account_not_found' | 'account_exists' | 'password_policy' | 'passwords_do_not_match' | 'rate_limited' | 'network' | 'unknown';
+/** An MFA delivery option offered by the identity platform. */
+export interface UdsMfaMethod {
+    /** Stable identifier passed back to `selectMfaMethod`. */
+    id: string;
+    /** Primary label, e.g. "Authenticator app". */
+    label: string;
+    /** Optional supporting copy, e.g. "Ending in ••3312". */
+    description?: string;
+    /** Renders the option as non-selectable. */
+    disabled?: boolean;
+}
+/**
+ * What the identity platform needs next.
+ *
+ * This is the heart of the contract: the provider reports the *state of the
+ * authentication attempt*, and the pattern decides what to render. Every major
+ * identity platform already returns a challenge/next-step object of this shape,
+ * so adapters stay thin.
+ */
+export type UdsAuthResult = 
+/** Authentication is complete. */
+{
+    status: 'success';
+    session?: UdsSession;
+}
+/** The identifier was accepted; a password is now required. */
+ | {
+    status: 'password_required';
+}
+/** The user must choose how to receive a one-time code. */
+ | {
+    status: 'mfa_required';
+    methods: UdsMfaMethod[];
+}
+/** A one-time code must be entered. */
+ | {
+    status: 'otp_required';
+    /** The method the code was sent to, used for the on-screen explanation. */
+    method?: UdsMfaMethod;
+    /** Number of digits to render. Defaults to the card's `otpLength`. */
+    codeLength?: number;
+    /** How long until a resend is permitted. Drives the built-in throttle. */
+    resendAfterMs?: number;
+}
+/** The credentials were valid but the password must be changed before sign-in. */
+ | {
+    status: 'password_reset_required';
+}
+/** A recovery link was dispatched. `destination` is shown back to the user if present. */
+ | {
+    status: 'reset_link_sent';
+    destination?: string;
+}
+/** A username reminder was dispatched. */
+ | {
+    status: 'username_sent';
+    destination?: string;
+}
+/** The account is temporarily locked. */
+ | {
+    status: 'locked';
+    unlockAfterMs?: number;
+}
+/** The attempt failed. The pattern maps `code` to approved user-facing copy. */
+ | {
+    status: 'error';
+    code: UdsAuthErrorCode;
+    message?: string;
+};
+/**
+ * The authentication seam for `uds-pattern-login-card`.
+ *
+ * Only `signIn` is required. **Every other method is a capability**: the card
+ * renders the affordance for a method only when the adapter implements it, so
+ * there is no way to surface a link that leads nowhere, and no parallel set of
+ * `show-*` / `enable-*` booleans to keep in sync.
+ *
+ * | Implement… | …and the card renders |
+ * | --- | --- |
+ * | `requestPasswordReset` | the "Forgot password?" route |
+ * | `requestUsernameReminder` | the "Forgot username?" route |
+ * | `signUp` | the "Create one" route |
+ * | `resendOtp` | the "Resend code" affordance, with throttle |
+ */
+export interface UdsAuthProvider {
+    /**
+     * Begin authentication. Called with just the identifier for an
+     * identifier-first flow, or with both fields when the card collected them
+     * together.
+     */
+    signIn(input: {
+        identifier: string;
+        password?: string;
+        rememberIdentifier?: boolean;
+    }): Promise<UdsAuthResult>;
+    /**
+     * Verify the password of an identifier-first flow. When omitted, the card
+     * falls back to calling `signIn` with both fields.
+     */
+    verifyPassword?(input: {
+        identifier: string;
+        password: string;
+    }): Promise<UdsAuthResult>;
+    /** Choose an MFA delivery method. Required if `signIn` can return `mfa_required`. */
+    selectMfaMethod?(input: {
+        methodId: string;
+    }): Promise<UdsAuthResult>;
+    /** Verify a one-time code. Required if any method can return `otp_required`. */
+    verifyOtp?(input: {
+        code: string;
+    }): Promise<UdsAuthResult>;
+    /** Re-dispatch the one-time code. Presence enables the resend affordance. */
+    resendOtp?(): Promise<UdsAuthResult>;
+    /** Start password recovery. Presence enables the "Forgot password?" route. */
+    requestPasswordReset?(input: {
+        identifier: string;
+    }): Promise<UdsAuthResult>;
+    /** Start username recovery. Presence enables the "Forgot username?" route. */
+    requestUsernameReminder?(input: {
+        email: string;
+    }): Promise<UdsAuthResult>;
+    /** Set a new password. Required if any method can return `password_reset_required`. */
+    resetPassword?(input: {
+        password: string;
+    }): Promise<UdsAuthResult>;
+    /** Register a new account. Presence enables the sign-up route. */
+    signUp?(input: {
+        firstName: string;
+        lastName: string;
+        identifier: string;
+    }): Promise<UdsAuthResult>;
+}
+/**
+ * Identity helper that gives adapter authors type inference and a single place
+ * to add shared behaviour later (telemetry, retry, logging) without changing
+ * every call site.
+ *
+ * ```ts
+ * const auth = createAuthProvider({
+ *   signIn: ({ identifier, password }) => oktaSdk.authn(identifier, password),
+ *   verifyOtp: ({ code }) => oktaSdk.verifyFactor(code),
+ * });
+ * ```
+ */
+export declare function createAuthProvider<T extends UdsAuthProvider>(provider: T): T;

package/dist/types/providers/control-strategy.d.ts

@@ -0,0 +1,144 @@
+import { UdsAuthErrorCode, UdsAuthResult, UdsSession } from './auth-provider';
+import { UdsLoginStep } from '../utils/types';
+/**
+ * An interceptor around one workflow checkpoint.
+ *
+ * `next` is the pattern's own behaviour. Call it to keep the default and adapt
+ * the result, or ignore it to replace the checkpoint outright.
+ */
+export type UdsInterceptor<TContext, TOutcome> = (context: TContext, next: () => TOutcome) => TOutcome;
+/** What the workflow should do next. Returned by the transition checkpoints. */
+export type UdsLoginTransition = {
+    type: 'goto';
+    step: UdsLoginStep;
+} | {
+    type: 'stay';
+} | {
+    type: 'fail';
+    code: UdsAuthErrorCode;
+    message?: string;
+};
+/** Moves the workflow to `step`. */
+export declare const goTo: (step: UdsLoginStep) => UdsLoginTransition;
+/** Leaves the workflow where it is. */
+export declare const stay: () => UdsLoginTransition;
+/** Surfaces a failure without moving. */
+export declare const fail: (code: UdsAuthErrorCode, message?: string) => UdsLoginTransition;
+/** Values collected on the step being submitted. */
+export type UdsLoginValues = Record<string, string | boolean>;
+export interface UdsLoginSubmitContext {
+    /** The step being submitted. */
+    step: UdsLoginStep;
+    /** The values the user entered on this step. */
+    values: Readonly<UdsLoginValues>;
+    /** The identifier the workflow is authenticating, carried across steps. */
+    identifier: string;
+}
+export interface UdsLoginTransitionContext {
+    /** The provider result being translated into a step. */
+    result: UdsAuthResult;
+    /** The step the workflow is on. */
+    from: UdsLoginStep;
+}
+/** Why the workflow is moving. */
+export type UdsLoginNavigationCause = 
+/** The user followed an in-card link. */
+'link'
+/** The workflow advanced itself (for example, a lone MFA method was auto-selected). */
+ | 'auto'
+/** `reset()` was called. */
+ | 'reset';
+export interface UdsLoginNavigateContext {
+    from: UdsLoginStep;
+    /** Where the pattern intends to go. */
+    to: UdsLoginStep;
+    cause: UdsLoginNavigationCause;
+}
+export interface UdsLoginFailureContext {
+    code: UdsAuthErrorCode;
+    /** The step the failure happened on. */
+    step: UdsLoginStep;
+    /** Any diagnostic text the provider attached. Never rendered. */
+    message?: string;
+}
+/** How a failure should be surfaced. */
+export interface UdsLoginFailureOutcome {
+    /** The copy to display. `undefined` suppresses the alert. */
+    text?: string;
+    /** Optionally move the workflow as well — for example to a dedicated page. */
+    transition?: UdsLoginTransition;
+}
+export interface UdsLoginCompleteContext {
+    /** The session the provider returned, when it supplied one. */
+    session?: UdsSession;
+}
+/**
+ * The single seam for changing how the login workflow *behaves*.
+ *
+ * The pattern owns the workflow; this is how a consumer alters its course
+ * without taking the whole machine back. Every decision point the workflow has
+ * is a checkpoint here, so a change of path is expressed in one object rather
+ * than assembled from a handful of independent props — which is what made the
+ * previous `controlled` + `step` + `loading` + `errorMessage` arrangement so
+ * easy to get half-right.
+ *
+ * Checkpoints run in workflow order:
+ *
+ * | Checkpoint | Fires | Default |
+ * | --- | --- | --- |
+ * | `submit` | before the provider is consulted | calls the provider method for the step |
+ * | `transition` | on every provider result | maps the result to a step |
+ * | `navigate` | on every step change | performs the move |
+ * | `failure` | on every failure | maps the code to approved copy |
+ * | `complete` | on success | emits `udsLoginSuccess` |
+ *
+ * ```ts
+ * card.controlStrategy = {
+ *   // Step into the flow: require acceptance of terms before a new password.
+ *   transition: (ctx, next) => {
+ *     const outcome = next();
+ *     if (outcome.type === 'goto' && outcome.step === 'reset-password' && !termsAccepted) {
+ *       return goTo('check-email');
+ *     }
+ *     return outcome;
+ *   },
+ *
+ *   // Hand sign-up off to a separate journey entirely.
+ *   navigate: (ctx, next) => {
+ *     if (ctx.to === 'sign-up') {
+ *       router.push('/register');
+ *       return stay();
+ *     }
+ *     return next();
+ *   },
+ * };
+ * ```
+ *
+ * Every hook is optional, and omitting one means "use the pattern's behaviour".
+ * Because `next()` is always available, a strategy that only *observes* — for
+ * analytics or telemetry — is a one-liner that cannot accidentally change the
+ * flow.
+ */
+export interface UdsLoginControlStrategy {
+    /**
+     * Wraps the provider call for a step. Return a `UdsAuthResult` to drive the
+     * workflow as though the provider had produced it — useful for inserting a
+     * CAPTCHA, a device check, or a consent gate ahead of the real call.
+     */
+    submit?: UdsInterceptor<UdsLoginSubmitContext, Promise<UdsAuthResult>>;
+    /** Wraps the mapping from a provider result to the next step. */
+    transition?: UdsInterceptor<UdsLoginTransitionContext, UdsLoginTransition>;
+    /** Wraps every step change, whether user-driven or automatic. */
+    navigate?: UdsInterceptor<UdsLoginNavigateContext, UdsLoginTransition>;
+    /** Wraps failure presentation — the copy shown, and optionally a redirect. */
+    failure?: UdsInterceptor<UdsLoginFailureContext, UdsLoginFailureOutcome>;
+    /** Wraps successful completion. */
+    complete?: UdsInterceptor<UdsLoginCompleteContext, void>;
+}
+/**
+ * Runs a checkpoint through the strategy, falling back to the pattern's own
+ * behaviour when the strategy does not intercept it.
+ */
+export declare function intercept<TContext, TOutcome>(interceptor: UdsInterceptor<TContext, TOutcome> | undefined, context: TContext, fallback: () => TOutcome): TOutcome;
+/** Identity helper giving a strategy literal its types without a type annotation. */
+export declare function createControlStrategy<T extends UdsLoginControlStrategy>(strategy: T): T;

package/dist/types/providers/login-config.d.ts

@@ -0,0 +1,52 @@
+import { UdsAuthProvider } from './auth-provider';
+import { UdsLoginControlStrategy } from './control-strategy';
+import { UdsLoginLabels } from '../utils/types';
+/**
+ * Everything a login pattern is configured with that cannot be an attribute.
+ *
+ * ## Why this object exists
+ *
+ * Custom element attributes are strings. Stencil will coerce `string`,
+ * `number` and `boolean` for you, but an object or a function can only be
+ * assigned as a JS property — there is no attribute form. That splits the
+ * configuration surface in two whether we like it or not, so the convention
+ * makes the split explicit rather than letting it emerge by accident:
+ *
+ * > **If it can be an attribute, it is one. Everything that cannot — objects
+ * > and functions — lives here, in exactly one `config` object.**
+ *
+ * The rule is mechanical, so "should this be a prop or go in config?" is
+ * answerable in review by looking at the type rather than debating taste. It
+ * also bounds the growth of the element's prop list: new seams (telemetry,
+ * theming, validation) land as members of this object instead of as another
+ * top-level property, which is the proliferation problem that the aggregate
+ * `UdsLoginControlStrategy` was introduced to solve one level down.
+ *
+ * Every member is optional. A card with no config at all is inert but valid —
+ * it renders the first step and reports that it has no provider.
+ *
+ * ```ts
+ * card.config = {
+ *   auth: createAuthProvider({ signIn: … }),
+ *   control: { navigate: (ctx, next) => … },
+ *   labels: { identifierHeading: 'Iniciar sesión' },
+ * };
+ * ```
+ */
+export interface UdsLoginConfig {
+    /**
+     * The authentication seam: an adapter that answers *what the identity
+     * platform needs next*. Supplying one is how the pattern is used.
+     */
+    auth?: UdsAuthProvider;
+    /**
+     * The control seam: interceptors over the workflow's checkpoints, for
+     * altering *where this product's journey differs*. See
+     * `UdsLoginControlStrategy`.
+     */
+    control?: UdsLoginControlStrategy;
+    /** Partial override of the card's copy, for localisation. */
+    labels?: Partial<UdsLoginLabels>;
+}
+/** Identity helper giving a config literal its types without an annotation. */
+export declare function createLoginConfig<T extends UdsLoginConfig>(config: T): T;

package/dist/types/providers/memory-auth-provider.d.ts

@@ -0,0 +1,37 @@
+import { UdsAuthProvider, UdsMfaMethod } from './auth-provider';
+/** Shape of the fake directory backing {@link createMemoryAuthProvider}. */
+export interface MemoryAuthUser {
+    identifier: string;
+    password: string;
+    /** When set, sign-in challenges for one of these before succeeding. */
+    mfaMethods?: UdsMfaMethod[];
+    /** The code `verifyOtp` accepts. Defaults to `'555555'`. */
+    otpCode?: string;
+    /** Forces the `password_reset_required` branch on successful password entry. */
+    mustResetPassword?: boolean;
+}
+export interface MemoryAuthOptions {
+    users?: MemoryAuthUser[];
+    /** Consecutive failures before the account locks. Defaults to 3. */
+    maxAttempts?: number;
+    /** Resend throttle reported on `otp_required`. Defaults to 30 000 ms. */
+    resendAfterMs?: number;
+    /** Omit capabilities to exercise the card's capability detection. */
+    capabilities?: {
+        signUp?: boolean;
+        requestPasswordReset?: boolean;
+        requestUsernameReminder?: boolean;
+        resendOtp?: boolean;
+    };
+}
+/**
+ * An in-memory reference implementation of {@link UdsAuthProvider}.
+ *
+ * It exists so the demo harness and the test suite can drive the *real*
+ * workflow — identifier → password → MFA choice → OTP → success, plus the
+ * recovery, lockout and sign-up branches — without a network or an identity
+ * platform. It is also the worked example adapter authors copy from.
+ *
+ * Not intended for production use: it compares passwords in plain text.
+ */
+export declare function createMemoryAuthProvider(options?: MemoryAuthOptions): UdsAuthProvider;

package/dist/types/providers/parse-auth-result.d.ts

@@ -0,0 +1,8 @@
+import { UdsAuthResult } from './auth-provider';
+/**
+ * Validates a provider's response, returning it narrowed to `UdsAuthResult`.
+ *
+ * @param value what the adapter returned
+ * @param source the provider method called, for the diagnostic message
+ */
+export declare function parseAuthResult(value: unknown, source: string): UdsAuthResult;

package/dist/types/slimmer/common/log.d.ts

@@ -0,0 +1,8 @@
+/** Console wrapper carrying a GP prefix, so framework diagnostics are traceable. */
+export declare class LogUtility {
+    private static readonly PREFIX;
+    private static readonly PREFIX_STYLE;
+    static log(...message: unknown[]): void;
+    static warn(...message: unknown[]): void;
+    static error(...message: unknown[]): void;
+}

package/dist/types/slimmer/common/symbols.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Internal markers used to attach slimmer wiring to component and slimmer
+ * instances without colliding with any real field name.
+ */
+/** On a slimmer prototype: the list of component methods it hooks into. */
+export declare const SlimmerMappedMethod: unique symbol;
+/** On a slimmer instance: the component that injected it. */
+export declare const SlimmerConsumedBy: unique symbol;
+/** On a component instance: the slimmers it has injected, keyed by field name. */
+export declare const ConsumerSlimmers: unique symbol;

package/dist/types/slimmer/common/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A prototype or instance as a decorator sees it: an indexable property bag.
+ *
+ * The upstream snapshot typed these positions as `new (...args) => T`, which
+ * describes a *constructor* rather than the prototype object a property
+ * decorator is actually handed. That slips through a loose config but not this
+ * repo's `strict` mode, so we model it honestly and keep the casts contained
+ * to `asBag` instead of scattering them through every decorator.
+ */
+export type PropertyBag = Record<PropertyKey, any>;
+/** Narrows the `Object` a decorator is handed to something indexable. */
+export declare const asBag: (target: object) => PropertyBag;
+export type Nullable<T> = T | undefined | null;
+export type MapToComponentFieldOptions = {
+    /** The component field to bind to, when it differs from the slimmer field name. */
+    componentFieldName?: string;
+    /**
+     * Allows the slimmer to write back to the component field.
+     *
+     * Read-only by default, and a given field should be writable from **one**
+     * slimmer only — that keeps "who can change this" answerable by looking at a
+     * single file, which is the maintainability problem this framework exists to
+     * solve.
+     */
+    writable?: boolean;
+};
+export type SlimmerMappedMethodEntry = {
+    componentMethodName: string;
+    slimmerMethodName: string;
+};

package/dist/types/slimmer/decorators/inject-slimmer.d.ts

@@ -0,0 +1,24 @@
+import { UdsSlimmer } from './slimmer';
+import { PropertyBag } from '../common/types';
+/**
+ * Marks a component field as a slimmer injection point.
+ *
+ * ```ts
+ * class UdsPatternLoginCard {
+ *   @InjectSlimmer() private workflow = new WorkflowSlimmer();
+ * }
+ * ```
+ *
+ * The decorator replaces the field with an accessor pair, so assigning the
+ * instance in the field initialiser is what performs the injection: the slimmer
+ * is handed a back-reference to the component and any `@MapToComponentMethod`
+ * hooks it declares are attached.
+ *
+ * Note this relies on field initialisers compiling to assignment rather than
+ * `Object.defineProperty` — i.e. `useDefineForClassFields` must be off, which is
+ * the default below an ES2022 target. With define semantics the initialiser
+ * would shadow this accessor on the instance and nothing would be wired up.
+ */
+export declare function InjectSlimmer<T extends UdsSlimmer>(): PropertyDecorator;
+export declare function createSlimmerFieldSetter<T extends UdsSlimmer>(fieldName: PropertyKey): (this: PropertyBag, slimmer: T) => void;
+export declare function createSlimmerFieldGetter(fieldName: PropertyKey): (this: PropertyBag) => unknown;

package/dist/types/slimmer/decorators/map-to-component-field.d.ts

@@ -0,0 +1,16 @@
+import { MapToComponentFieldOptions } from '../common/types';
+/**
+ * Binds a slimmer field to a field on the component that injected it:
+ *
+ * - reading the slimmer field returns the component's current value;
+ * - writing it updates the component (only when `writable` is set).
+ *
+ * The slimmer therefore holds no copy of the state. That matters inside a
+ * Stencil component, where the component's `@State()` fields are the values the
+ * renderer actually observes — a slimmer-local duplicate would drift and would
+ * not trigger re-renders.
+ *
+ * The slimmer field name is used as the component field name unless
+ * `componentFieldName` says otherwise.
+ */
+export declare function MapToComponentField(options?: MapToComponentFieldOptions): PropertyDecorator;

package/dist/types/slimmer/decorators/map-to-component-method.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Hooks a slimmer method onto a component method of the given name.
+ *
+ * When the component method runs, the slimmer method runs after it and its
+ * return value becomes the result. The hook is one-way: calling the slimmer
+ * method directly does not invoke the component's.
+ *
+ * Typical targets are Stencil lifecycle methods (`componentWillLoad`,
+ * `disconnectedCallback`), `@Watch` handlers, and `@Method()` members.
+ */
+export declare function MapToComponentMethod(componentMethodName: string): PropertyDecorator;

package/dist/types/slimmer/decorators/slimmer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Base class for every slimmer.
+ *
+ * A slimmer owns exactly one responsibility lifted out of a component class —
+ * the workflow machine, OTP input behaviour, a throttle timer. It reaches back
+ * into its host component only through the two mapping decorators, which keeps
+ * the coupling declarative and greppable.
+ */
+export declare abstract class UdsSlimmer {
+}

package/dist/types/slimmer/index.d.ts

@@ -0,0 +1,6 @@
+export * from './decorators/slimmer';
+export * from './decorators/inject-slimmer';
+export * from './decorators/map-to-component-field';
+export * from './decorators/map-to-component-method';
+export * from './common/symbols';
+export type { MapToComponentFieldOptions, Nullable, PropertyBag, SlimmerMappedMethodEntry } from './common/types';