@providame/vue 0.0.7 → 0.0.9

package/README.md

@@ -46,6 +46,26 @@ import { SignIn } from '@providame/vue'
 </template>
 ```
 
+### Component props
+
+`SignIn`, `SignUp`, and `ResetPassword` all accept `title`, `subtitle`, and
+`logo`. `title` defaults to a branding-aware heading (e.g. "Sign in to Acme")
+once your environment's app name loads; `logo` defaults to your configured
+branding logo.
+
+`SignUp` additionally accepts:
+
+- `collect-name` (default `true`) — toggles the first/last name fields.
+- `invite-token` — **required** when your environment's signup-policy mode is
+  `invite_only`: the single-use code from an admin-generated signup-invite
+  email. Read it from your own app's invite-accept URL and pass it through —
+  it threads directly to `CreateSignUpParams.inviteToken`. Every other
+  signup-policy mode ignores it if set.
+
+```vue
+<SignUp :collect-name="false" invite-token="tok_..." />
+```
+
 ### Modal vs. page usage
 
 These components serve two contexts, and the footer link behaves differently
@@ -77,9 +97,284 @@ The listener takes precedence when both it and a URL are supplied.
 import { useSignIn } from '@providame/vue'
 
 const signIn = useSignIn()
+
+// Preferred — one guarded call for the common identifier + password case.
 await signIn.signInWithPassword('user@example.com', 'password')
+
+// Equivalent, longhand — useful if you need to do something between the two
+// steps, e.g. show a separate password screen after the identifier is entered.
+await signIn.create('user@example.com')
+await signIn.attemptFirstFactor({ strategy: 'password', password: 'password' })
+
+if (signIn.isComplete.value) {
+  // signIn.session.value is set
+}
+```
+
+### Passwordless sign-in & MFA (`useSignIn`)
+
+Beyond password sign-in, `useSignIn()` exposes passkey, email-OTP, SMS-OTP,
+and magic-link sign-in, plus mid-flow TOTP enrollment. The prebuilt `<SignIn>`
+above already wires password and passkey sign-in — email-OTP, SMS-OTP, and
+magic-link are **headless-only** escape hatches; build your own UI around
+them if you need one.
+
+```ts
+import { useSignIn } from '@providame/vue'
+const signIn = useSignIn()
+
+// Passkey — opens the flow and immediately prompts navigator.credentials.get().
+await signIn.signInWithPasskey(identifier, window.location.hostname)
+
+// Email one-time code (first factor)
+await signIn.signInWithOTPEmail(identifier)
+await signIn.attemptFirstFactor({ strategy: 'otp_email', code })
+await signIn.resendOTPEmail()
+
+// SMS one-time code (first factor) — identifier is still email; the code is
+// texted to whatever phone number is on file for that account.
+await signIn.signInWithOTPSMS(identifier)
+await signIn.attemptFirstFactor({ strategy: 'otp_sms', code })
+await signIn.resendOTPSMS()
+
+// Magic link — emails a passwordless "click to sign in" link pointing at returnUrl.
+await signIn.signInWithMagicLink(identifier, 'https://myapp.com/auth/callback')
+
+// Mid-flow TOTP, reached from any of the strategies above.
+if (signIn.status.value === 'needs_second_factor') {
+  await signIn.attemptSecondFactor({ strategy: 'totp', code })
+}
+if (signIn.status.value === 'needs_mfa_enrollment') {
+  await signIn.enrollTotp() // -> signIn.enrollment.value = { secret, otpauthUri }
+  await signIn.verifyTotpEnrollment(code)
+}
+
+signIn.reset() // back to "idle"
+```
+
+`firstFactors`/`secondFactors` report what the backend will accept next;
+`recoveryCodes` is populated right after a mid-flow TOTP enrollment.
+
+### Sign-up (`useSignUp`)
+
+`useSignUp()` mirrors `useSignIn()` — same reactive-state shape, for
+registration. The prebuilt `<SignUp>` already wires all of this; reach for
+the composable directly to build a fully custom sign-up UI.
+
+```ts
+import { useSignUp } from '@providame/vue'
+const signUp = useSignUp()
+
+await signUp.create({
+  email,
+  password,
+  firstName, // optional
+  lastName, // optional
+  inviteToken, // required only when signup-policy mode is invite_only
+  turnstileToken, // required only when bot-check is enabled for this environment
+})
+
+if (signUp.needsVerification.value) {
+  await signUp.attemptVerification({ code })
+}
+
+// Post-registration second factor, if the environment's MFA policy requires one.
+if (signUp.status.value === 'needs_second_factor') {
+  await signUp.attemptSecondFactor({ strategy: 'totp', code })
+}
+
+// Forced enrollment on a brand-new account.
+if (signUp.status.value === 'needs_mfa_enrollment') {
+  await signUp.enrollTotp() // -> signUp.enrollment.value = { secret, otpauthUri }
+  await signUp.verifyTotpEnrollment(code)
+}
+
+if (signUp.isComplete.value) {
+  // signUp.session.value is set; signUp.recoveryCodes.value may carry backup codes
+} else if (signUp.isWaitlisted.value) {
+  // verified, but this environment's signup-policy mode is "waitlist" — no session issued yet
+}
+
+signUp.reset()
+```
+
+### Password reset (`useResetPassword`, `<ResetPassword>`)
+
+```vue
+<script setup>
+import { ResetPassword } from '@providame/vue'
+</script>
+
+<template>
+  <ResetPassword sign-in-url="/sign-in" @complete="onComplete" />
+</template>
+```
+
+The prebuilt `<SignIn>` already embeds this whole flow behind its "Forgot
+password?" link — mount `<ResetPassword>` on its own route only if you want
+it reachable directly (e.g. from a password-reset email link).
+
+```ts
+import { useResetPassword } from '@providame/vue'
+const reset = useResetPassword()
+
+await reset.create({ email })
+await reset.attempt({ code, password }) // sets the new password and signs in
+
+// Mid-flow TOTP, same shape as useSignIn/useSignUp.
+if (reset.status.value === 'needs_second_factor') {
+  await reset.attemptSecondFactor({ strategy: 'totp', code })
+}
+if (reset.status.value === 'needs_mfa_enrollment') {
+  await reset.enrollTotp() // -> reset.enrollment.value = { secret, otpauthUri }
+  await reset.verifyTotpEnrollment(code)
+}
+
+await reset.resend() // re-send the reset code
+reset.reset() // back to "idle"
 ```
 
+`attempt()`/`attemptSecondFactor()`/`enrollTotp()`/`verifyTotpEnrollment()`/`resend()`
+all throw if called before `create()` — there's no flow yet to act on.
+
+## What's in the box
+
+**Components** — `SignIn`, `SignUp`, `ResetPassword`, `UserButton`, `UserProfile`,
+`SignInButton`, `SignUpButton`, `SignOutButton`, `SignedIn`, `SignedOut`,
+`Protect`, `RedirectToSignIn`, `OrganizationSwitcher`, `OrganizationProfile`,
+`CreateOrganization`.
+
+**Composables** — `useAuth`, `useUser`, `useSession`, `useSignIn`, `useSignUp`,
+`useSignInIdp`, `useResetPassword`, `useOrganization`, `useOrganizationList`,
+`useBranding`, `usePasskeyRegistrationLink`, `useProvidame`.
+
+Every composable returns `Ref`s — including the functions, matching Clerk's own
+Vue SDK. So it's `await getToken.value()`, not `getToken()`.
+
+## Organizations
+
+```vue
+<script setup>
+import { OrganizationSwitcher, OrganizationProfile, useOrganization } from '@providame/vue'
+
+// Reads token claims — makes no request
+const { organization, roles, permissions, has } = useOrganization()
+</script>
+
+<template>
+  <OrganizationSwitcher />
+  <OrganizationProfile />
+</template>
+```
+
+`useOrganization()` covers the **active** organization only and never fetches —
+the token already carries `org_id`/`org_slug`/`org_roles`/`org_permissions`.
+`useOrganizationList()` does fetch, since the full membership list isn't in a
+token; it also exposes `setActive(orgId)`.
+
+`<OrganizationProfile>` gates each action on the caller's own `org:sys_*`
+permissions rather than a role name, so it works with roles you define yourself.
+Pass `organization-id` to render a specific organization instead of the
+session's active one.
+
+`<OrganizationSwitcher>` accepts `hide-create` (drop "Create organization",
+for apps that provision organizations centrally), `personal-label` (relabel
+the no-organization option — Clerk calls it "Personal account"), and
+`hide-personal` (drop that option entirely, for a B2B-only app where every
+user belongs to an organization).
+
+## Gating UI
+
+```vue
+<Protect role="admin">...</Protect>
+<Protect org-permission="org:sys_memberships:manage">...</Protect>
+<Protect role="admin" org-role="org:admin">...</Protect>   <!-- both must pass -->
+```
+
+`role`/`permission` gate on environment-level grants; `org-role`/`org-permission`
+gate on the active organization. Omitted props are not constraints. **This is UI
+gating only** — real enforcement is your backend verifying the token, via
+`@providame/backend`.
+
+## Object-scoped access
+
+`<Protect>` reads claims already in the token — synchronous, free, never fails.
+`<Can>` asks a question about one specific resource — a network call, so it
+needs a loading state and can fail:
+
+```vue
+<Can permission="edit" resource="document:42">
+  <template #loading><Spinner /></template>
+  <template #fallback>You can't edit this document.</template>
+  <button>Edit</button>
+</Can>
+```
+
+Use `<Protect role="admin">` for "is this user an admin"; use `<Can permission="edit" resource="document:42">`
+for "can this user edit *this* document". `<Can>` fails **closed** — a network
+error renders `#fallback`, never the default slot. `useCan({ permission, resource })`
+is the headless equivalent, returning `{ allowed, isLoading, error }`.
+
+Answers are cached per-question for the life of the session (cleared on
+sign-in/out and organization switch) — mounting `<Can>` for the same resource
+twice on one page costs one request, not two.
+
+`<Can>` also accepts an optional `context` prop (a plain object) that passes
+extra values through for conditional/attribute-based permissions — e.g.
+checking a permission that's only granted below a certain amount or within a
+certain region.
+
+## Branding & the underlying client
+
+`useBranding()` is called internally by every prebuilt component above —
+reach for it directly only if you're building a fully custom UI and want the
+same environment-configured colors/logo applied to it:
+
+```ts
+import { useBranding } from '@providame/vue'
+
+// Fetched once and memoized on the client instance — mounting several
+// components that call this on one page costs a single request, not one
+// per component. Also applies the colors as global CSS custom properties
+// (--providame-accent/-bg/-fg and their -dark counterparts).
+const branding = useBranding() // Ref<Branding>
+
+branding.value.logoUrl // string | undefined
+branding.value.primaryColor
+branding.value.appName
+```
+
+`useProvidame()` returns the underlying `Providame` client instance every
+composable in this package is built on — every other composable calls this
+internally, so you only need it directly to reach a client method this
+package doesn't already wrap:
+
+```ts
+import { useProvidame } from '@providame/vue'
+
+const providame = useProvidame()
+
+await providame.configuration() // { turnstileSiteKey, tosUrl, privacyUrl, helpUrl, supportEmail, ... }
+await providame.branding() // same data useBranding() applies automatically
+providame.organizations // OrganizationsApi — used internally by <OrganizationProfile>
+```
+
+## Theming
+
+Every component accepts an `appearance` prop:
+
+```vue
+<SignIn :appearance="{ variables: { colorPrimary: '#111827' } }" />
+```
+
+Components also fetch your environment's configured branding (colors, logo,
+light and dark) on mount and apply it automatically, so an unstyled `appearance`
+prop is usually unnecessary.
+
+## Docs
+
+Full reference: `/docs/sdk/vue` in your Providame dashboard.
+
 ## Build
 
 ```bash

package/dist/components/Can.vue.d.ts

@@ -0,0 +1,22 @@
+type __VLS_Props = {
+    permission: string;
+    resource?: string;
+    context?: Record<string, unknown>;
+};
+declare var __VLS_1: {}, __VLS_3: {}, __VLS_5: {};
+type __VLS_Slots = {} & {
+    loading?: (props: typeof __VLS_1) => any;
+} & {
+    default?: (props: typeof __VLS_3) => any;
+} & {
+    fallback?: (props: typeof __VLS_5) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/CreateOrganization.vue.d.ts

@@ -0,0 +1,14 @@
+import "../styles.css";
+import { type Appearance } from "@providame/core";
+type __VLS_Props = {
+    appearance?: Appearance;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    created: (organizationId: string) => any;
+    cancel: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onCreated?: ((organizationId: string) => any) | undefined;
+    onCancel?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/OrganizationProfile.vue.d.ts

@@ -0,0 +1,14 @@
+import "../styles.css";
+import { type Appearance } from "@providame/core";
+type __VLS_Props = {
+    appearance?: Appearance;
+    /** Defaults to the session's ACTIVE organization. */
+    organizationId?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    close: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onClose?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/OrganizationSwitcher.vue.d.ts

@@ -0,0 +1,21 @@
+import "../styles.css";
+import { type Appearance } from "@providame/core";
+type __VLS_Props = {
+    appearance?: Appearance;
+    /** Hide the "Create organization" action for apps that provision centrally. */
+    hideCreate?: boolean;
+    /**
+     * Label for the no-organization option. Clerk calls this "Personal
+     * account"; a B2B app with no personal mode can pass its own wording or
+     * drop the option entirely with `hidePersonal`.
+     */
+    personalLabel?: string;
+    hidePersonal?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    change: (organizationId: string | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onChange?: ((organizationId: string | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/Protect.vue.d.ts

@@ -1,5 +1,8 @@
 type __VLS_Props = {
     role?: string;
+    permission?: string;
+    orgRole?: string;
+    orgPermission?: string;
 };
 declare var __VLS_1: {}, __VLS_3: {};
 type __VLS_Slots = {} & {

package/dist/composables/useCan.d.ts

@@ -0,0 +1,16 @@
+import { type Ref } from "vue";
+import type { CanInput } from "@providame/core";
+export interface UseCanResult {
+    /** null while the first check for the current input is still in flight. */
+    allowed: Ref<boolean | null>;
+    isLoading: Ref<boolean>;
+    error: Ref<Error | null>;
+}
+/** Watches a (possibly reactive) authorization question and keeps `allowed`
+ * in step with it, re-checking whenever the input changes.
+ *
+ * A guard against a superseded response overwriting a newer one: input can
+ * change again before a request resolves (e.g. a resource prop changing
+ * twice quickly), and without tracking which run is current, a slow first
+ * response could land after a faster second one and show stale state. */
+export declare function useCan(input: Ref<CanInput>): UseCanResult;

package/dist/composables/useOrganization.d.ts

@@ -0,0 +1,36 @@
+import { type ComputedRef } from "vue";
+export interface ActiveOrganizationInfo {
+    id: string;
+    slug: string;
+    name: string;
+}
+export interface UseOrganization {
+    /** False until the session's claims have loaded. */
+    isLoaded: ComputedRef<boolean>;
+    /** The active organization, or null when none is set. */
+    organization: ComputedRef<ActiveOrganizationInfo | null>;
+    /** Roles held in the active organization, across both tiers. */
+    roles: ComputedRef<string[]>;
+    /** Permissions resolved from those roles. */
+    permissions: ComputedRef<string[]>;
+    /** Whether the active organization grants a role. */
+    has: (params: {
+        role?: string;
+        permission?: string;
+    }) => boolean;
+}
+/**
+ * The session's ACTIVE organization, read straight from its access-token
+ * claims.
+ *
+ * Deliberately makes no network request: the token already carries
+ * org_id/org_slug/org_name/org_roles/org_permissions, so anything this
+ * composable could fetch would be strictly staler than what it already has.
+ * Use `useOrganizationList()` to enumerate every organization the user
+ * belongs to, or to switch which one is active.
+ *
+ * Display and gating only — these claims come from an unverified client-side
+ * decode. Real authorization belongs on the customer's own backend, which
+ * verifies the token's signature first.
+ */
+export declare function useOrganization(): UseOrganization;

package/dist/composables/useOrganizationList.d.ts

@@ -0,0 +1,29 @@
+import { type Ref } from "vue";
+import type { MyOrganization } from "@providame/core";
+export interface UseOrganizationList {
+    /** False until the first load completes (successfully or not). */
+    isLoaded: Ref<boolean>;
+    /** Every organization the signed-in user belongs to, with their own roles. */
+    organizations: Ref<MyOrganization[]>;
+    /** The most recent load error, or null. */
+    error: Ref<Error | null>;
+    /** Re-fetches the list. */
+    reload: () => Promise<void>;
+    /**
+     * Switches the active organization and returns the freshly minted token's
+     * claims to the client, so subsequent `useOrganization()` reads reflect
+     * the new organization without waiting out the previous token's ~60s life.
+     * Pass null to clear.
+     */
+    setActive: (organizationId: string | null) => Promise<void>;
+}
+/**
+ * Every organization the signed-in user belongs to, plus the ability to
+ * switch which one is active.
+ *
+ * Unlike `useOrganization()` — which reads the active organization straight
+ * from token claims and makes no request — this fetches
+ * `GET /fapi/v1/me/organizations`, since the full membership list is not
+ * something a token carries.
+ */
+export declare function useOrganizationList(): UseOrganizationList;

package/dist/index.d.ts

@@ -5,9 +5,12 @@ export { useSignUp, type UseSignUp } from "./composables/useSignUp.js";
 export { useSession, type UseSession } from "./composables/useSession.js";
 export { useResetPassword, type UseResetPassword } from "./composables/useResetPassword.js";
 export { useAuth, type UseAuth } from "./composables/useAuth.js";
+export { useOrganization, type ActiveOrganizationInfo, type UseOrganization, } from "./composables/useOrganization.js";
+export { useOrganizationList, type UseOrganizationList, } from "./composables/useOrganizationList.js";
 export { useUser, type UseUser } from "./composables/useUser.js";
 export { useBranding } from "./composables/useBranding.js";
 export { usePasskeyRegistrationLink, type UsePasskeyRegistrationLink, } from "./composables/usePasskeyRegistrationLink.js";
+export { useCan, type UseCanResult } from "./composables/useCan.js";
 export { default as SignIn } from "./components/SignIn.vue";
 export { default as SignUp } from "./components/SignUp.vue";
 export { default as ResetPassword } from "./components/ResetPassword.vue";
@@ -20,5 +23,9 @@ export { default as SignInButton } from "./components/SignInButton.vue";
 export { default as SignUpButton } from "./components/SignUpButton.vue";
 export { default as SignOutButton } from "./components/SignOutButton.vue";
 export { default as UserProfile } from "./components/UserProfile.vue";
+export { default as OrganizationSwitcher } from "./components/OrganizationSwitcher.vue";
+export { default as OrganizationProfile } from "./components/OrganizationProfile.vue";
+export { default as CreateOrganization } from "./components/CreateOrganization.vue";
+export { default as Can } from "./components/Can.vue";
 export type { Branding, Configuration, EnabledIdp, EndUserInfo, EnrollTotpResponse, FactorKind, FlowStatus, ProvidameOptions, MeUser, Session, } from "@providame/core";
 export { ProvidameError, verifyToken } from "@providame/core";