@hexclave/js 1.0.2 → 1.0.5

package/src/lib/hexclave-app/common.ts

@@ -0,0 +1,209 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { ProviderType } from "@hexclave/shared/dist/utils/oauth";
+import type { GenericQueryCtx, UserIdentity } from "convex/server";
+export type {
+  DefaultHandlerUrlTarget,
+  HandlerPageUrls,
+  HandlerRedirectUrls,
+  HandlerUrlOptions,
+  HandlerUrlTarget,
+  HandlerUrls,
+  ResolvedHandlerUrls,
+} from "@hexclave/shared/dist/interface/handler-urls";
+
+export type RedirectToOptions = {
+  replace?: boolean,
+  noRedirectBack?: boolean,
+};
+
+export type AsyncStoreProperty<Name extends string, Args extends any[], Value, IsMultiple extends boolean> =
+  & { [key in `${IsMultiple extends true ? "list" : "get"}${Capitalize<Name>}`]: (...args: Args) => Promise<Value> }
+
+export type EmailConfig = {
+  host: string,
+  port: number,
+  username: string,
+  password: string,
+  senderEmail: string,
+  senderName: string,
+}
+
+export type RedirectMethod = "window"
+  | "none"
+  | {
+    useNavigate: () => (to: string) => void,
+    navigate?: (to: string) => void,
+  }
+
+
+export type GetCurrentUserOptions<HasTokenStore> =
+  & {
+    or?: 'redirect' | 'throw' | 'return-null' | 'anonymous' | /** @deprecated */ 'anonymous-if-exists[deprecated]',
+    /**
+     * Whether to include restricted users (users who haven't completed onboarding requirements like email verification).
+     * By default, restricted users are filtered out (treated similar to anonymous users).
+     *
+     * Note: This option cannot be set to false when `or: 'anonymous'` is used, as all anonymous users are also restricted.
+     *
+     * @default false
+     */
+    includeRestricted?: boolean,
+    tokenStore?: TokenStoreInit,
+  }
+  & (HasTokenStore extends false ? {
+    tokenStore: TokenStoreInit,
+  } : {});
+
+export type ConvexCtx =
+| GenericQueryCtx<any>
+| { auth: { getUserIdentity: () => Promise<UserIdentity | null> } };
+
+export type GetCurrentPartialUserOptions<HasTokenStore> =
+  & {
+    or?: 'return-null' | 'anonymous-if-exists',  // note: unlike normal getUser, 'anonymous' still returns null sometimes (eg. if no token is present)
+    tokenStore?: TokenStoreInit,
+  }
+  & (
+    | {
+      from: 'token',
+    }
+    | {
+      from: 'convex',
+      ctx: ConvexCtx,
+    }
+  )
+  & (HasTokenStore extends false ? {
+    tokenStore: TokenStoreInit,
+  } : {});
+
+export type RequestLike = {
+  headers:
+    | {
+      get: (name: string) => string | null,
+    }
+    | Record<string, string | null>,
+};
+
+export type TokenStoreInit<HasTokenStore extends boolean = boolean> =
+  HasTokenStore extends true ? (
+    | "cookie"
+    | "nextjs-cookie"
+    | "memory"
+    | RequestLike
+    | { accessToken: string, refreshToken: string }
+  )
+  : HasTokenStore extends false ? null
+  : TokenStoreInit<true> | TokenStoreInit<false>;
+
+export type OAuthScopesOnSignIn = {
+  [key in ProviderType]: string[];
+};
+
+/**
+ * Contains the authentication methods without session-related fields.
+ * Used for apps that have token storage capabilities.
+ */
+export type AuthLike<ExtraOptions = {}> = {
+  signOut(options?: { redirectUrl?: URL | string } & ExtraOptions): Promise<void>,
+  signOut(options?: { redirectUrl?: URL | string }): Promise<void>,
+
+  /**
+   * Returns the current access token, or null if the user is not signed in.
+   *
+   * The access token is a short-lived JWT that can be used to authenticate requests to external servers.
+   * It will be automatically refreshed when it expires.
+   */
+  getAccessToken(options?: {} & ExtraOptions): Promise<string | null>,
+
+  /**
+   * Returns the current refresh token, or null if the user is not signed in.
+   *
+   * The refresh token is a long-lived token that can be used to obtain new access tokens.
+   * It should be kept secret and never exposed to the client.
+   */
+  getRefreshToken(options?: {} & ExtraOptions): Promise<string | null>,
+
+  /**
+   * Returns the value for the HTTP `Authorization` header for authenticated requests to external servers.
+   * Most commonly used in cross-origin requests. Similar to `getAuthJson`, but specifically for HTTP requests.
+   *
+   * If you are using `tokenStore: "cookie"`, you don't need this for same-origin requests. However, most
+   * browsers now disable third-party cookies by default, so we must pass authentication tokens by header instead
+   * if the client and server are on different origins.
+   *
+   * This function returns the header value in this format:
+   * `Bearer stackauth_<base64(getAuthJson())>`, or `null` if the user is not signed in.
+   * You can use this with `fetch` or other HTTP request libraries to send authenticated requests.
+   *
+   * On the server, you can then pass in the `Request` object to the `tokenStore` option
+   * of your Stack app. Please note that CORS does not allow most headers by default, so you
+   * must include `authorization` in the [`Access-Control-Allow-Headers` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)
+   * of the CORS preflight response.
+   *
+   * If you are not using HTTP (and hence cannot set headers), use `getAuthJson()` instead.
+   *
+   * Example:
+   *
+   * ```ts
+   * // client
+   * const authorizationHeader = await hexclaveApp.getAuthorizationHeader();
+   * const res = await fetch("https://api.example.com", {
+   *   headers: {
+   *     ...(authorizationHeader ? { Authorization: authorizationHeader } : {})
+   *     // you can also add your own headers here
+   *   },
+   * });
+   *
+   * // server
+   * function handleRequest(req: Request) {
+   *   const user = await hexclaveServerApp.getUser({ tokenStore: req });
+   *   return new Response("Welcome, " + user.displayName);
+   * }
+   * ```
+   */
+  getAuthorizationHeader(options?: {} & ExtraOptions): Promise<string | null>,
+
+  /**
+   * @deprecated Use `getAuthorizationHeader()` instead.
+   *
+   * Returns the legacy `x-stack-auth` headers for authenticated HTTP requests. This remains for backwards
+   * compatibility with existing integrations.
+   */
+  getAuthHeaders(options?: {} & ExtraOptions): Promise<{ "x-stack-auth": string }>,
+  /** @deprecated Use `useAuthorizationHeader()` instead. */
+
+  /**
+   * Creates a JSON-serializable object containing the information to authenticate a user on an external server.
+   * Similar to `getAuthorizationHeader`, but returns an object that can be sent over any protocol instead of just
+   * HTTP headers.
+   *
+   * While `getAuthorizationHeader` is the recommended way to send authentication tokens over HTTP, your app may use
+   * a different protocol, for example WebSockets or gRPC. This function returns a token object that can be JSON-serialized and sent to the server in any way you like.
+   *
+   * On the server, you can pass in this token object into the `tokenStore` option to fetch user details.
+   *
+   * Example:
+   *
+   * ```ts
+   * // client
+   * const res = await rpcCall(rpcEndpoint, {
+   *   data: {
+   *     auth: await hexclaveApp.getAuthJson(),
+   *   },
+   * });
+   *
+   * // server
+   * function handleRequest(data) {
+   *   const user = await hexclaveServerApp.getUser({ tokenStore: data.auth });
+   *   return new Response("Welcome, " + user.displayName);
+   * }
+   * ```
+   */
+  getAuthJson(options?: {} & ExtraOptions): Promise<{ accessToken: string | null, refreshToken: string | null }>,
+};
+
+/** @internal */
+export const hexclaveAppInternalsSymbol = Symbol.for("StackAuth--DO-NOT-USE-OR-YOU-WILL-BE-FIRED--StackAppInternals");

package/src/lib/hexclave-app/connected-accounts/index.ts

@@ -0,0 +1,47 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { KnownErrors } from "@hexclave/shared";
+import { Result } from "@hexclave/shared/dist/utils/results";
+
+export type Connection = {
+  /**
+   * @deprecated Use `provider` instead. This field returns the provider for backward compatibility.
+   */
+  id: string,
+  /** Provider config ID (e.g., "google", "github") */
+  provider: string,
+  /** Account ID from the OAuth provider (e.g., Google user ID) */
+  providerAccountId: string,
+};
+
+export type OAuthConnection = {
+  /**
+   * Get an OAuth access token for this connected account.
+   *
+   * Returns `{ status: "ok", data: { accessToken } }` on success, or
+   * `{ status: "error", error: KnownErrors["OAuthAccessTokenNotAvailable"] }` if the
+   * refresh token has been revoked/expired or the requested scopes are not available.
+   *
+   * @param options.scopes - If provided, only returns a token that has all of these scopes.
+   */
+  getAccessToken(options?: { scopes?: string[] }): Promise<Result<{ accessToken: string }, KnownErrors["OAuthAccessTokenNotAvailable"]>>,
+  /**
+   * React hook to get an OAuth access token for this connected account.
+   *
+   * Returns `{ status: "ok", data: { accessToken } }` on success, or
+   * `{ status: "error", error: KnownErrors["OAuthAccessTokenNotAvailable"] }` if the
+   * refresh token has been revoked/expired or the requested scopes are not available.
+   *
+   * @param options.scopes - If provided, only returns a token that has all of these scopes.
+   */
+} & Connection;
+
+/**
+ * @deprecated Used by legacy `getConnectedAccount(providerId)`. Use `OAuthConnection` instead,
+ * which returns a `Result` from `getAccessToken`/`useAccessToken` instead of throwing.
+ */
+export type DeprecatedOAuthConnection = {
+  getAccessToken(): Promise<{ accessToken: string }>,
+} & Connection;

package/src/lib/hexclave-app/contact-channels/index.ts

@@ -0,0 +1,80 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { ContactChannelsCrud } from "@hexclave/shared/dist/interface/crud/contact-channels";
+
+
+export type ContactChannel = {
+  id: string,
+  value: string,
+  type: 'email',
+  isPrimary: boolean,
+  isVerified: boolean,
+  usedForAuth: boolean,
+
+  sendVerificationEmail(options?: { callbackUrl?: string }): Promise<void>,
+  update(data: ContactChannelUpdateOptions): Promise<void>,
+  delete(): Promise<void>,
+}
+
+export type ContactChannelCreateOptions = {
+  value: string,
+  type: 'email',
+  usedForAuth: boolean,
+  isPrimary?: boolean,
+}
+
+export function contactChannelCreateOptionsToCrud(userId: string, options: ContactChannelCreateOptions): ContactChannelsCrud["Client"]["Create"] {
+  return {
+    value: options.value,
+    type: options.type,
+    used_for_auth: options.usedForAuth,
+    is_primary: options.isPrimary,
+    user_id: userId,
+  };
+}
+
+export type ContactChannelUpdateOptions = {
+  usedForAuth?: boolean,
+  value?: string,
+  isPrimary?: boolean,
+}
+
+export function contactChannelUpdateOptionsToCrud(options: ContactChannelUpdateOptions): ContactChannelsCrud["Client"]["Update"] {
+  return {
+    value: options.value,
+    used_for_auth: options.usedForAuth,
+    is_primary: options.isPrimary,
+  };
+}
+
+export type ServerContactChannel = ContactChannel & {
+  update(data: ServerContactChannelUpdateOptions): Promise<void>,
+}
+export type ServerContactChannelUpdateOptions = ContactChannelUpdateOptions & {
+  isVerified?: boolean,
+}
+
+export function serverContactChannelUpdateOptionsToCrud(options: ServerContactChannelUpdateOptions): ContactChannelsCrud["Server"]["Update"] {
+  return {
+    value: options.value,
+    is_verified: options.isVerified,
+    used_for_auth: options.usedForAuth,
+    is_primary: options.isPrimary,
+  };
+}
+
+export type ServerContactChannelCreateOptions = ContactChannelCreateOptions & {
+  isVerified?: boolean,
+}
+export function serverContactChannelCreateOptionsToCrud(userId: string, options: ServerContactChannelCreateOptions): ContactChannelsCrud["Server"]["Create"] {
+  return {
+    type: options.type,
+    value: options.value,
+    is_verified: options.isVerified,
+    user_id: userId,
+    used_for_auth: options.usedForAuth,
+    is_primary: options.isPrimary,
+  };
+}

package/src/lib/hexclave-app/customers/index.ts

@@ -0,0 +1,158 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { inlineProductSchema } from "@hexclave/shared/dist/schema-fields";
+import * as yup from "yup";
+import { AsyncStoreProperty } from "../common";
+
+export type InlineProduct = yup.InferType<typeof inlineProductSchema>;
+
+export type Item = {
+  displayName: string,
+  /**
+   * May be negative.
+   */
+  quantity: number,
+  /**
+   * Equal to Math.max(0, quantity).
+   */
+  nonNegativeQuantity: number,
+};
+
+export type ServerItem = Item & {
+  increaseQuantity(amount: number): Promise<void>,
+  /**
+   * Decreases the quantity by the given amount.
+   *
+   * Note that you may want to use tryDecreaseQuantity instead, as it will prevent the quantity from going below 0 in a race-condition-free way.
+   */
+  decreaseQuantity(amount: number): Promise<void>,
+  /**
+   * Decreases the quantity by the given amount and returns true if the result is non-negative; returns false and does nothing if the result would be negative.
+   *
+   * Most useful for pre-paid credits.
+   */
+  tryDecreaseQuantity(amount: number): Promise<boolean>,
+};
+
+export type CustomerProduct = {
+  id: string | null,
+  quantity: number,
+  displayName: string,
+  customerType: "user" | "team" | "custom",
+  isServerOnly: boolean,
+  stackable: boolean,
+  /** @deprecated Product ownership is independent of purchase type. Will be removed in a future version. */
+  type?: "one_time" | "subscription",
+  subscription: null | {
+    subscriptionId: string | null,
+    currentPeriodEnd: Date | null,
+    cancelAtPeriodEnd: boolean,
+    isCancelable: boolean,
+  },
+  switchOptions?: Array<{
+    productId: string,
+    displayName: string,
+    prices: InlineProduct["prices"],
+  }>,
+};
+
+export type CustomerProductsList = CustomerProduct[] & {
+  nextCursor: string | null,
+};
+
+export type CustomerProductsListOptions = {
+  cursor?: string,
+  limit?: number,
+};
+
+export type CustomerProductsRequestOptions =
+  | ({ userId: string } & CustomerProductsListOptions)
+  | ({ teamId: string } & CustomerProductsListOptions)
+  | ({ customCustomerId: string } & CustomerProductsListOptions);
+
+export type CustomerInvoiceStatus = "draft" | "open" | "paid" | "uncollectible" | "void" | null;
+
+export type CustomerInvoice = {
+  createdAt: Date,
+  status: CustomerInvoiceStatus,
+  amountTotal: number,
+  hostedInvoiceUrl: string | null,
+};
+
+export type CustomerInvoicesList = CustomerInvoice[] & {
+  nextCursor: string | null,
+};
+
+export type CustomerInvoicesListOptions = {
+  cursor?: string,
+  limit?: number,
+};
+
+export type CustomerInvoicesRequestOptions =
+  | ({ userId: string } & CustomerInvoicesListOptions)
+  | ({ teamId: string } & CustomerInvoicesListOptions);
+
+export type CustomerDefaultPaymentMethod = {
+  id: string,
+  brand: string | null,
+  last4: string | null,
+  exp_month: number | null,
+  exp_year: number | null,
+} | null;
+
+export type CustomerBilling = {
+  hasCustomer: boolean,
+  defaultPaymentMethod: CustomerDefaultPaymentMethod,
+};
+
+export type CustomerPaymentMethodSetupIntent = {
+  clientSecret: string,
+  stripeAccountId: string,
+};
+
+export type Customer<IsServer extends boolean = false> =
+  & {
+    readonly id: string,
+
+    createCheckoutUrl(options: (
+      | { productId: string, returnUrl?: string }
+      | (IsServer extends true ? { product: InlineProduct, returnUrl?: string } : never)
+    )): Promise<string>,
+
+    createPaymentMethodSetupIntent(): Promise<CustomerPaymentMethodSetupIntent>,
+
+    setDefaultPaymentMethodFromSetupIntent(setupIntentId: string): Promise<CustomerDefaultPaymentMethod>,
+
+    switchSubscription(options: { fromProductId: string, toProductId: string, priceId?: string, quantity?: number }): Promise<void>,
+  }
+  & AsyncStoreProperty<
+    "billing",
+    [],
+    CustomerBilling,
+    false
+  >
+  & AsyncStoreProperty<
+    "item",
+    [itemId: string],
+    IsServer extends true ? ServerItem : Item,
+    false
+  >
+  & AsyncStoreProperty<
+    "products",
+    [options?: CustomerProductsListOptions],
+    CustomerProductsList,
+    true
+  >
+  & AsyncStoreProperty<
+    "invoices",
+    [options?: CustomerInvoicesListOptions],
+    CustomerInvoicesList,
+    true
+  >
+  & (IsServer extends true ? {
+    grantProduct(
+      product: { productId: string, quantity?: number } | { product: InlineProduct, quantity?: number },
+    ): Promise<void>,
+  } : {});

package/src/lib/hexclave-app/data-vault/index.ts

@@ -0,0 +1,12 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { AsyncStoreProperty } from "../common";
+
+export type DataVaultStore =
+  & {
+    id: string,
+    setValue: (key: string, value: string, options: { secret: string }) => Promise<void>,
+  }
+ & AsyncStoreProperty<"value", [key: string, options: { secret: string }], string | null, false>;