@axcode/axcloud-sdk 0.4.0-dev.f5f8764 → 0.4.0-dev.f9603ab

package/README.md

@@ -441,6 +441,32 @@ function Dashboard() {
 }
 ```
 
+### 8. Membership applications with a section choice
+
+```tsx
+import { createFormHelper } from '@axcode/axcloud-sdk';
+
+const forms = createFormHelper({
+  apiUrl: 'https://api.axcloud.app/forms',
+  apiKey: import.meta.env.VITE_AXCLOUD_FORMS_API_KEY, // forms:submit only
+  site: 'example.org',
+});
+
+// Sections the organization ticked as selectable, e.g. [{ id: 'section_x', name: 'SAS' }]
+const sections = await forms.getMembershipSections();
+
+// Either the chosen section…
+await forms.submitMembership(email, { firstName, lastName, sectionId: sections[0].id });
+// …or a company without a section of its own.
+await forms.submitMembership(email, { firstName, lastName, company: 'Example Air' });
+```
+
+The API refuses a `sectionId` that is not in the list. The approval in the console invites
+the applicant into the chosen section. `getMembershipSections` throws when the API refuses
+(for example when the membership form is not enabled), so a site can fall back to a free-text
+company field. The call is checked with the forms key like a submission but does not count toward
+the key's rate limit, and browsers may keep the answer for five minutes.
+
 ## API Reference
 
 ### Provider

package/dist/index.d.mts

@@ -55,6 +55,29 @@ interface FormSubmissionResponse {
     /** Unique submission ID */
     submissionId: string;
 }
+/**
+ * A section an organization offers in its public membership application,
+ * typically an airline or other employer with a section of its own
+ */
+interface MembershipSection {
+    /** Send as `sectionId` in the membership application data */
+    id: string;
+    /** The name to show the applicant */
+    name: string;
+}
+/**
+ * Membership application data. Name the applicant's section with `sectionId`
+ * (one of {@link getMembershipSections}); for a company without a section of
+ * its own, send its name as `company` instead.
+ */
+interface MembershipApplicationData {
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    sectionId?: string;
+    company?: string;
+    [key: string]: unknown;
+}
 /**
  * Form submission stored in database
  */
@@ -138,6 +161,34 @@ interface FormSubmissionsResponse {
  * ```
  */
 declare function submitForm(apiUrl: string, submission: FormSubmission): Promise<FormSubmissionResponse>;
+/**
+ * List the sections an organization offers in its public membership application
+ *
+ * Uses the same public forms API key and site as a submission, but does not
+ * count toward the key's rate limit, so asking on every page view never uses
+ * up what submissions need. Only sections the organization has made
+ * selectable are returned; the list is empty when there are none.
+ * Throws when the API refuses, for example when the membership form is not
+ * enabled, so a site can fall back to a free-text company field.
+ *
+ * @param apiUrl - AxCloud Forms API base URL (e.g., 'https://api.axcloud.app/forms')
+ * @param options - The public forms API key and the site domain
+ * @returns The sections, sorted by the name the applicant sees
+ *
+ * @example
+ * ```tsx
+ * const sections = await getMembershipSections('https://api.axcloud.app/forms', {
+ *   apiKey: 'your-org-forms-key',
+ *   site: 'example.org'
+ * })
+ * // [{ id: 'section_x', name: 'SAS' }, ...]
+ * ```
+ */
+declare function getMembershipSections(apiUrl: string, options: {
+    apiKey: string;
+    site: string;
+    signal?: AbortSignal;
+}): Promise<MembershipSection[]>;
 /**
  * Create a form submission helper with pre-configured API URL, API key, and site
  *
@@ -178,12 +229,13 @@ declare function createFormHelper(config: {
     /**
      * Submit a membership application
      */
-    submitMembership: (email: string, data: {
-        firstName?: string;
-        lastName?: string;
-        phone?: string;
-        [key: string]: unknown;
-    }) => Promise<FormSubmissionResponse>;
+    submitMembership: (email: string, data: MembershipApplicationData) => Promise<FormSubmissionResponse>;
+    /**
+     * List the sections offered in the membership application
+     */
+    getMembershipSections: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<MembershipSection[]>;
     /**
      * Generic submit function
      */
@@ -1408,4 +1460,4 @@ interface LinkedAccountsListProps {
  */
 declare function LinkedAccountsList({ providers, showConnectButtons, className, onUnlink, onLinkInitiated, renderIdentity, renderAvailableProvider, }: LinkedAccountsListProps): React.JSX.Element;
 
-export { type Auth0ClientState, type AuthUser, type AvailableProvider, AxCloudAnalyticsOptions, AxCloudError, type AxCloudErrorCode, AxCloudModule, AxCloudProvider, type Ballot, type BallotCandidate, type BallotOption, type BallotSeat, type CastVoteResult, type CodeEligibility, ContentListResponse, ContentQueryOptions, DocumentFolder, DocumentFolderListResponse, DocumentItem, DocumentListResponse, DocumentQueryOptions, type EmailVerificationResult, type FormStatsResponse, type FormSubmission, type FormSubmissionRecord, type FormSubmissionResponse, type FormSubmissionsResponse, LinkedAccountsList, type LinkedAccountsListProps, type LinkedIdentity, LoginButton, LogoutButton, MediaItem, MediaListResponse, ModuleGate, type MyProfileResponse, NewsItem, Organization, OrganizationBranding, ProtectedRoute, Section, SignedDocumentUrl, SignedMediaUrl, type UpdateMyProfileInput, type UseAuthReturn, type UseLinkedAccountsReturn, User$1 as User, type UserApiResponse, type UserOrganizationMembership, type UserOrganizationSection, UserRole, type VoteReceipt, castVote, castVoteWithCode, checkEligibility, checkVotingCode, createFormHelper, getBallot, getVotingReceipt, isAxCloudError, submitForm, useAuth, useAvatar, useBranding, useCodeBallot, useDocumentDownload, useDocuments, useFormStats, useForms, useLinkedAccounts, useLogo, useMedia, useMediaList, useMemberDocumentDownload, useMemberDocumentFolders, useMemberDocuments, useModuleAccess, useMySection, useNews, useOrg, useSections, useUpdateFormSubmission, useUpdateMyProfile, useUser };
+export { type Auth0ClientState, type AuthUser, type AvailableProvider, AxCloudAnalyticsOptions, AxCloudError, type AxCloudErrorCode, AxCloudModule, AxCloudProvider, type Ballot, type BallotCandidate, type BallotOption, type BallotSeat, type CastVoteResult, type CodeEligibility, ContentListResponse, ContentQueryOptions, DocumentFolder, DocumentFolderListResponse, DocumentItem, DocumentListResponse, DocumentQueryOptions, type EmailVerificationResult, type FormStatsResponse, type FormSubmission, type FormSubmissionRecord, type FormSubmissionResponse, type FormSubmissionsResponse, LinkedAccountsList, type LinkedAccountsListProps, type LinkedIdentity, LoginButton, LogoutButton, MediaItem, MediaListResponse, type MembershipApplicationData, type MembershipSection, ModuleGate, type MyProfileResponse, NewsItem, Organization, OrganizationBranding, ProtectedRoute, Section, SignedDocumentUrl, SignedMediaUrl, type UpdateMyProfileInput, type UseAuthReturn, type UseLinkedAccountsReturn, User$1 as User, type UserApiResponse, type UserOrganizationMembership, type UserOrganizationSection, UserRole, type VoteReceipt, castVote, castVoteWithCode, checkEligibility, checkVotingCode, createFormHelper, getBallot, getMembershipSections, getVotingReceipt, isAxCloudError, submitForm, useAuth, useAvatar, useBranding, useCodeBallot, useDocumentDownload, useDocuments, useFormStats, useForms, useLinkedAccounts, useLogo, useMedia, useMediaList, useMemberDocumentDownload, useMemberDocumentFolders, useMemberDocuments, useModuleAccess, useMySection, useNews, useOrg, useSections, useUpdateFormSubmission, useUpdateMyProfile, useUser };

package/dist/index.d.ts

@@ -55,6 +55,29 @@ interface FormSubmissionResponse {
     /** Unique submission ID */
     submissionId: string;
 }
+/**
+ * A section an organization offers in its public membership application,
+ * typically an airline or other employer with a section of its own
+ */
+interface MembershipSection {
+    /** Send as `sectionId` in the membership application data */
+    id: string;
+    /** The name to show the applicant */
+    name: string;
+}
+/**
+ * Membership application data. Name the applicant's section with `sectionId`
+ * (one of {@link getMembershipSections}); for a company without a section of
+ * its own, send its name as `company` instead.
+ */
+interface MembershipApplicationData {
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    sectionId?: string;
+    company?: string;
+    [key: string]: unknown;
+}
 /**
  * Form submission stored in database
  */
@@ -138,6 +161,34 @@ interface FormSubmissionsResponse {
  * ```
  */
 declare function submitForm(apiUrl: string, submission: FormSubmission): Promise<FormSubmissionResponse>;
+/**
+ * List the sections an organization offers in its public membership application
+ *
+ * Uses the same public forms API key and site as a submission, but does not
+ * count toward the key's rate limit, so asking on every page view never uses
+ * up what submissions need. Only sections the organization has made
+ * selectable are returned; the list is empty when there are none.
+ * Throws when the API refuses, for example when the membership form is not
+ * enabled, so a site can fall back to a free-text company field.
+ *
+ * @param apiUrl - AxCloud Forms API base URL (e.g., 'https://api.axcloud.app/forms')
+ * @param options - The public forms API key and the site domain
+ * @returns The sections, sorted by the name the applicant sees
+ *
+ * @example
+ * ```tsx
+ * const sections = await getMembershipSections('https://api.axcloud.app/forms', {
+ *   apiKey: 'your-org-forms-key',
+ *   site: 'example.org'
+ * })
+ * // [{ id: 'section_x', name: 'SAS' }, ...]
+ * ```
+ */
+declare function getMembershipSections(apiUrl: string, options: {
+    apiKey: string;
+    site: string;
+    signal?: AbortSignal;
+}): Promise<MembershipSection[]>;
 /**
  * Create a form submission helper with pre-configured API URL, API key, and site
  *
@@ -178,12 +229,13 @@ declare function createFormHelper(config: {
     /**
      * Submit a membership application
      */
-    submitMembership: (email: string, data: {
-        firstName?: string;
-        lastName?: string;
-        phone?: string;
-        [key: string]: unknown;
-    }) => Promise<FormSubmissionResponse>;
+    submitMembership: (email: string, data: MembershipApplicationData) => Promise<FormSubmissionResponse>;
+    /**
+     * List the sections offered in the membership application
+     */
+    getMembershipSections: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<MembershipSection[]>;
     /**
      * Generic submit function
      */
@@ -1408,4 +1460,4 @@ interface LinkedAccountsListProps {
  */
 declare function LinkedAccountsList({ providers, showConnectButtons, className, onUnlink, onLinkInitiated, renderIdentity, renderAvailableProvider, }: LinkedAccountsListProps): React.JSX.Element;
 
-export { type Auth0ClientState, type AuthUser, type AvailableProvider, AxCloudAnalyticsOptions, AxCloudError, type AxCloudErrorCode, AxCloudModule, AxCloudProvider, type Ballot, type BallotCandidate, type BallotOption, type BallotSeat, type CastVoteResult, type CodeEligibility, ContentListResponse, ContentQueryOptions, DocumentFolder, DocumentFolderListResponse, DocumentItem, DocumentListResponse, DocumentQueryOptions, type EmailVerificationResult, type FormStatsResponse, type FormSubmission, type FormSubmissionRecord, type FormSubmissionResponse, type FormSubmissionsResponse, LinkedAccountsList, type LinkedAccountsListProps, type LinkedIdentity, LoginButton, LogoutButton, MediaItem, MediaListResponse, ModuleGate, type MyProfileResponse, NewsItem, Organization, OrganizationBranding, ProtectedRoute, Section, SignedDocumentUrl, SignedMediaUrl, type UpdateMyProfileInput, type UseAuthReturn, type UseLinkedAccountsReturn, User$1 as User, type UserApiResponse, type UserOrganizationMembership, type UserOrganizationSection, UserRole, type VoteReceipt, castVote, castVoteWithCode, checkEligibility, checkVotingCode, createFormHelper, getBallot, getVotingReceipt, isAxCloudError, submitForm, useAuth, useAvatar, useBranding, useCodeBallot, useDocumentDownload, useDocuments, useFormStats, useForms, useLinkedAccounts, useLogo, useMedia, useMediaList, useMemberDocumentDownload, useMemberDocumentFolders, useMemberDocuments, useModuleAccess, useMySection, useNews, useOrg, useSections, useUpdateFormSubmission, useUpdateMyProfile, useUser };
+export { type Auth0ClientState, type AuthUser, type AvailableProvider, AxCloudAnalyticsOptions, AxCloudError, type AxCloudErrorCode, AxCloudModule, AxCloudProvider, type Ballot, type BallotCandidate, type BallotOption, type BallotSeat, type CastVoteResult, type CodeEligibility, ContentListResponse, ContentQueryOptions, DocumentFolder, DocumentFolderListResponse, DocumentItem, DocumentListResponse, DocumentQueryOptions, type EmailVerificationResult, type FormStatsResponse, type FormSubmission, type FormSubmissionRecord, type FormSubmissionResponse, type FormSubmissionsResponse, LinkedAccountsList, type LinkedAccountsListProps, type LinkedIdentity, LoginButton, LogoutButton, MediaItem, MediaListResponse, type MembershipApplicationData, type MembershipSection, ModuleGate, type MyProfileResponse, NewsItem, Organization, OrganizationBranding, ProtectedRoute, Section, SignedDocumentUrl, SignedMediaUrl, type UpdateMyProfileInput, type UseAuthReturn, type UseLinkedAccountsReturn, User$1 as User, type UserApiResponse, type UserOrganizationMembership, type UserOrganizationSection, UserRole, type VoteReceipt, castVote, castVoteWithCode, checkEligibility, checkVotingCode, createFormHelper, getBallot, getMembershipSections, getVotingReceipt, isAxCloudError, submitForm, useAuth, useAvatar, useBranding, useCodeBallot, useDocumentDownload, useDocuments, useFormStats, useForms, useLinkedAccounts, useLogo, useMedia, useMediaList, useMemberDocumentDownload, useMemberDocumentFolders, useMemberDocuments, useModuleAccess, useMySection, useNews, useOrg, useSections, useUpdateFormSubmission, useUpdateMyProfile, useUser };

package/dist/index.js

@@ -77,6 +77,26 @@ async function submitForm(apiUrl, submission) {
     throw primaryError;
   }
 }
+async function getMembershipSections(apiUrl, options) {
+  const baseUrl = apiUrl.replace(/\/$/, "");
+  const response = await fetch(
+    `${baseUrl}/public/membership-sections?site=${encodeURIComponent(options.site)}`,
+    {
+      method: "GET",
+      headers: { "X-Api-Key": options.apiKey },
+      signal: options.signal
+    }
+  );
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new Error(error.message || `Membership sections request failed (${response.status})`);
+  }
+  const result = await response.json().catch(() => ({}));
+  const sections = Array.isArray(result?.sections) ? result.sections : [];
+  return sections.filter(
+    (section) => !!section && typeof section.id === "string" && typeof section.name === "string"
+  ).map(({ id, name }) => ({ id, name }));
+}
 function createFormHelper(config) {
   return {
     /**
@@ -109,6 +129,14 @@ function createFormHelper(config) {
       email,
       data
     }),
+    /**
+     * List the sections offered in the membership application
+     */
+    getMembershipSections: (options = {}) => getMembershipSections(config.apiUrl, {
+      apiKey: config.apiKey,
+      site: config.site,
+      signal: options.signal
+    }),
     /**
      * Generic submit function
      */
@@ -1649,6 +1677,7 @@ exports.checkEligibility = checkEligibility;
 exports.checkVotingCode = checkVotingCode;
 exports.createFormHelper = createFormHelper;
 exports.getBallot = getBallot;
+exports.getMembershipSections = getMembershipSections;
 exports.getVotingReceipt = getVotingReceipt;
 exports.submitForm = submitForm;
 exports.useAuth = useAuth;