@ axcode/ axcloud-sdk (英语)

SDK用于与AxCloud CMS和成员管理建立网站. AxCloud 是个.. 无头:它拥有内容、出版物、访问控制和交付API,同时 消耗性应用程序拥有标记、布局和设计.

安装

npm install @axcode/axcloud-sdk

版本标记

SDK发布时有两种不同环境的标记:

建议的生产设置:

决定 latest 并锁定文件:

npm install --save-exact @axcode/axcloud-sdk@latest

{
  "dependencies": {
    "@axcode/axcloud-sdk": "0.3.1"
  }
}

在 CI 或部署时不要安装移动标记 。 测试特定 next 在需要时,将版本放在分支中,然后促进和固定稳定释放.

快速启动

匿名公共网站( 无 Auth0)

没有会员登录的公共产品站点应当导入专用的 供养. 它挂载 SDK 客户端, React 查询缓存和隐私安全分析 不导入或初始化 Auth0 :

import { AxCloudPublicProvider } from '@axcode/axcloud-sdk/public';

<AxCloudPublicProvider
  orgId="barnsport"
  apiUrl="https://api.axcloud.app"
  stage="prod"
  apiKey="pk_live_barnsport_read_submit"
>
  <App />
</AxCloudPublicProvider>;

公共网站可以通过相同的Auth0免费阅读已公布的 CMS 内容 进入点。 草稿和预览内容仅可通过 已认证主控台 :

import { usePageContent } from '@axcode/axcloud-sdk/public';

function HomeHero() {
  const content = usePageContent('home', { lang: 'sv', publicOnly: true });
  return <h1>{content.text('hero.title', 'Fallback title')}</h1>;
}

对于非反应适配器和增量迁移,创建相同的范围d 未导入经认证的 SDK 根的 Barnsport 客户端 :

import { createPublicBarnsportClient } from '@axcode/axcloud-sdk/barnsport';

const barnsport = createPublicBarnsportClient({ apiUrl, apiKey, orgId: 'barnsport' });
const providers = await barnsport.listProviders({ q: 'fotboll', limit: 5 });

使用浏览器安全密钥,仅限于网站所需的公共范围. 执行 不使用 AxCloudPublicProvider 用于成员或管理员特性。 现有 经认证的应用程序继续使用 AxCloudProvider 不变.

Barnsport 产品客户端和钩子

Barnsport 类型, 核心客户端和 React shocks 可以从一个单独的 其他产品不装入 Barnsport 代码:

import {
  useBarnsportProviderSearch,
  useBarnsportProvider,
  useSubmitBarnsportReview,
  useTrackBarnsportEvent,
} from '@axcode/axcloud-sdk/barnsport';

const providers = useBarnsportProviderSearch({ q: searchText, limit: 5 });
const provider = useBarnsportProvider(providerSlug);

供应商审查和产品活动仍然是Barnsport域名数据。 SDK这个 通过 AxCloud Barnsport 代理来引导它们; 它不把它们存储在 通用内容服务.

1. 用 AxCloud 程序包装您的应用程序

import { AxCloudProvider } from '@axcode/axcloud-sdk';

function App() {
  return (
    <AxCloudProvider
      orgId="org_ba81807b" // Your organization ID
      apiUrl="https://api.axcloud.app"
      apiKey="pk_live_..." // Public API key from Settings → API Keys
      auth0={{
        domain: 'auth.axcloud.app',
        clientId: 'your-client-id',
        redirectUri: window.location.origin,
        organization: 'org_auth0_...', // Optional Auth0 Organization ID for invite-only member sites
      }}
    >
      <Router>
        <Routes />
      </Router>
    </AxCloudProvider>
  );
}

orgId 是 CMS API 使用的 AxCloud 组织ID,例如 org_ba81807b。 。 。 . auth0.organization 是登录时使用的 Auth0 组织ID,例如 org_o960yILn77d4vY6u。 。 。 . 设定 auth0.organization 对只邀请的客户成员网站,因此通用登录范围属于该客户组织.

客户自有身份提供者

一个组织可以通过自己的Auth0租户认证AxCloud 继续提供内容、成员和授权API。 配置 完整、经审查的供应商在第一当事方地点静态地翻转:

<AxCloudProvider
  orgId="org_customer"
  apiUrl="https://dev-api.axcloud.app"
  stage="dev"
  auth0={{
    identityProviderId: 'idp_customer_dev',
    domain: 'dev-auth.customer.example',
    clientId: 'customer-member-spa-client-id',
    audience: 'https://api.axcloud.app',
    organization: 'org_customer_auth0',
    redirectUri: window.location.origin,
  }}
>
  <App />
</AxCloudProvider>

identityProviderId 是公开的 AxCloud 标识符,而不是证书。 没错 包含在 SDK 缓存所有者签名中, 因此是提供者切换或旋转 无法重用身份约束的查询数据。 SDK 不发现提供者或 持有 Auth0 管理 API 证书。 保持域名 客户身份 观众, 组织 ID、 AxCloud 阶段和 API URL 一起作为特定环境 配置;从不将客户DEV租户与AxCloud PROD API相混合.

2. 获取内容

import { useNews } from '@axcode/axcloud-sdk';

function NewsPage() {
  const { data: news, isLoading, isError } = useNews();

  if (isLoading) return <Spinner />;
  if (isError) return <Error />;

  return (
    <ul>
      {news.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>
  );
}

内容交付: 这些钩子只返回已公布的快照. 当 用户被认证,访问内部、成员和部分内容 来源于已验证的符号。 匿名用户只接收公开内容. 客户提供的状态或区段识别资料绝不允许更广泛的访问.

页面和新闻可保存在 AxCloud 中一次,并附有翻译和每种语言的要求:

import { useContentItem, useNews } from '@axcode/axcloud-sdk';

function AboutPage({ locale }: { locale: 'sv' | 'en' }) {
  const { data: page } = useContentItem('pages', 'about-us', {
    lang: locale,
    publicOnly: true,
  });

  return <h1>{page?.title}</h1>;
}

function NewsList({ locale }: { locale: 'sv' | 'en' }) {
  const { data: news } = useNews({ lang: locale });

  return news.map((item) => <article key={item.id}>{item.title}</article>);
}

3. 添加认证

import { useAuth, LoginButton, LogoutButton, ProtectedRoute } from '@axcode/axcloud-sdk';

function Header() {
  const { isAuthenticated, user } = useAuth();

  return (
    <header>
      {isAuthenticated ? (
        <>
          <span>Welcome, {user.name}</span>
          <LogoutButton />
        </>
      ) : (
        <LoginButton>Sign In</LoginButton>
      )}
    </header>
  );
}

function MemberArea() {
  return (
    <ProtectedRoute>
      <MemberContent />
    </ProtectedRoute>
  );
}

SDK在产品场地内不断核查UI. 给自己的品牌 当通知 needsEmailVerification 事实 :

const { needsEmailVerification, requestEmailVerification, refreshUser } = useAuth();

if (needsEmailVerification) {
  // Render the product's own verification notice.
}

await requestEmailVerification({ returnTo: window.location.href });
await refreshUser();

API从认证的代币中解决接受者和组织. 返回URL被限制在组织配置的成员站点.

3b. 增加隐私安全分析

分析是可选和提供者独立的。 AxCloud 解决公众 从组织、地点钥匙、部署阶段和 当前主机名 。 SDK消费者从未收到Umami API密钥.

import { AxCloudProvider, useAnalytics } from '@axcode/axcloud-sdk';

<AxCloudProvider
  orgId="org_ba81807b"
  apiUrl="https://api.axcloud.app"
  stage="prod"
  analytics={{
    enabled: analyticsConsent === 'accepted',
    siteKey: 'member-site',
    normalizePath: (path) => path.replace(/^\/member\/news\/[^/]+/, '/member/news/:id'),
  }}
  auth0={auth0Config}
>
  <App />
</AxCloudProvider>;

SDK 跟踪 SPA 页面在跟踪器准备好后会更改. 查询字符串和 碎片被去除,常见的不透明ID被替换为 :id,不跟踪 除非 trackLocalhost: true 明确设置.

自定义事件必须允许在 AxCloud 分析站点配置中列出 :

function NewsArticle() {
  const analytics = useAnalytics();

  const handleOpen = () => {
    analytics.track('news_opened', { surface: 'member_news' });
  };
}

只发粗 en,布林斯和计数. SDK拒绝敏感 属性名称和类似电子邮件的值,但应用程序仍然负责 从不提供姓名、电子邮件地址、用户身份、文档标题、搜索文本, 聊天文本,或其他个人/内容数据. 生产跟踪器只能是 在产品的隐私通知和内容安全政策之后启用 已审查.

4. 使用部分

import { useMySection } from '@axcode/axcloud-sdk';

function MySectionPage() {
  const { section, members, isLoading } = useMySection();

  if (isLoading) return <Spinner />;
  if (!section) return <p>You are not assigned to a section</p>;

  return (
    <div>
      <h1>{section.name}</h1>
      <h2>Members ({members.length})</h2>
      <ul>
        {members.map((m) => (
          <li key={m.id}>{m.name}</li>
        ))}
      </ul>
    </div>
  );
}

4b. 节范围的内容

import { useNews, useMySection } from '@axcode/axcloud-sdk';

function SectionNews() {
  const { section } = useMySection();
  // AxCloud derives the allowed sections from the authenticated membership.
  const { data: visibleNews } = useNews();

  return (
    <div>
      <h2>Section News</h2>
      {visibleNews.map((item) => (
        <NewsCard key={item.id} item={item} />
      ))}
      {!section && <p>You are not assigned to a section.</p>}
    </div>
  );
}

5. 获取组织品牌和媒体

import { useBranding, useLogo, useMedia } from '@axcode/axcloud-sdk';

function Header() {
  const { logoUrl, branding, organizationName } = useBranding();

  return (
    <header style={{ backgroundColor: branding?.primaryColor }}>
      {logoUrl && <img src={logoUrl} alt={organizationName} />}
      <h1>{organizationName}</h1>
    </header>
  );
}

// Or just the logo
function Logo() {
  const { logoUrl, isLoading } = useLogo();

  if (isLoading) return <Skeleton />;
  return logoUrl ? <img src={logoUrl} alt="Logo" /> : <DefaultLogo />;
}

// Fetch specific media file
function HeroImage() {
  const { mediaUrl } = useMedia('hero-banner.jpg');
  return mediaUrl ? <img src={mediaUrl} alt="Hero" /> : null;
}

说明: 媒体URL由1小时后到期的S3 URL签名. SDK在到期前会自动刷新它们(时间:30分).

6. 获取公共文件

import { useDocuments, useDocumentDownload } from '@axcode/axcloud-sdk';

function PublicDocuments() {
  const { documents, isLoading } = useDocuments({ tags: ['handbook'], limit: 20 });

  if (isLoading) return <Skeleton />;
  return (
    <ul>
      {documents.map((doc) => (
        <li key={doc.document_id}>
          <DocumentLink documentId={doc.document_id} title={doc.title} />
        </li>
      ))}
    </ul>
  );
}

function DocumentLink({ documentId, title }: { documentId: string; title: string }) {
  const { documentUrl } = useDocumentDownload(documentId);
  return documentUrl ? <a href={documentUrl}>{title}</a> : <span>{title}</span>;
}

只有文档 status: "published" 财务报告和审定财务报表 audience: "public" 通过SDK文档钩被曝光.

7. 按单元划分的大门特征

import { ModuleGate, useOrg } from '@axcode/axcloud-sdk';

function Dashboard() {
  const { hasModule } = useOrg();

  return (
    <div>
      <NewsSection />

      <ModuleGate module="training" fallback={<UpgradePrompt />}>
        <TrainingSection />
      </ModuleGate>

      {hasModule('ai') && <AIChatWidget />}
    </div>
  );
}

8. 有章节选择的成员申请

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' });

API拒绝 sectionId 这不在名单上。 控制台的审批邀请 申请人进入选定的部分. getMembershipSections 当 API 拒绝时抛出 (例如,当会员表未启用时),所以一个网站可以倒回自由文本 公司领域。 使用表单键检查通话, 如提交文件, 但不计数到 键的速率限制,浏览器可能会将答案保存5分钟.

API 参考

提供者

钩子

配置自助服务被故意限制在个人接触领域. 组织名称, 电子邮件、角色、地位、组织和科级任务仍由管理员管理.

useUser() 规范对骆驼Case的API响应. 组织特有的价值观总是会出现 从会员中选出提供者 orgId数字 :

const {
  user,
  roleInOrg,
  title,
  section, // { id, name, role } | null
  sections, // all verified section memberships
  sectionId,
  sectionIds,
  memberSince, // normalized from joined_at
} = useUser();

return (
  <p>
    {section?.name ?? 'No section'} · member since {memberSince}
  </p>
);

import { useUpdateMyProfile } from '@axcode/axcloud-sdk';

function ProfileForm() {
  const updateProfile = useUpdateMyProfile();

  const save = () =>
    updateProfile.mutateAsync({
      firstName: 'Anna',
      lastName: 'Pilot',
      phone: '+46701234567',
      address: 'Flyggatan 1',
    });

  return (
    <button onClick={save} disabled={updateProfile.isPending}>
      Save profile
    </button>
  );
}

内容查询选项

interface ContentQueryOptions {
  page?: number; // Page number (default: 1)
  pageSize?: number; // Items per page (default: 20)
  search?: string; // Search in title/content
  sortBy?: 'publishedAt' | 'createdAt' | 'updatedAt' | 'title';
  sortOrder?: 'asc' | 'desc';
  tags?: string[];
  lang?: string; // Return translated title/slug/blocks when available
  publicOnly?: boolean; // Force public endpoint even when authenticated
}

收藏钩返回 data, (中文(简体) ), count, (中文(简体) ), total, (中文(简体) ), page, (中文(简体) ), pageSize, (中文(简体) ), hasMore, (中文(简体) ), nextCursor, (中文(简体) ), isLoading, (中文(简体) ), isFetching, (中文(简体) ), isError, (中文(简体) ), error 财务报告和审定财务报表 refetch。在 Auth0 的初始会话检查中, 成员能力钩等待 而不是简单地要求公开内容。 成员缓存被隔离 Auth0 科目,并在登录或账户更改时删除. 所有其他身份标记的 AxCloud 查询数据在同一边界被删除.

结构化槽是CMS的不可信输入. 偏爱 text(), (中文(简体) ), list() 财务报告和审定财务报表 image()。 。 。 . unsafeHtml() (和被堕落者) html() (别名)必须进行消毒 使用前为 dangerouslySetInnerHTML。 。 。 .

构成部分

高级使用

自定义 API 呼叫

import { useAuth } from '@axcode/axcloud-sdk';

function MyComponent() {
  const { getAccessToken } = useAuth();

  const fetchCustomData = async () => {
    const token = await getAccessToken();
    const response = await fetch('/api/custom', {
      headers: { Authorization: `Bearer ${token}` },
    });
    return response.json();
  };
}

访问基本的 Auth0 客户端

const { getAuth0Client } = useAuth();
const auth0 = getAuth0Client();

// Full Auth0 API available
await auth0.getAccessTokenSilently();
await auth0.getIdTokenClaims();

担保模式

API 密钥对认证托肯

SDK使用两种类型的证书:

1. API 密钥 (单位:千美元)apiKey 道具: A 公共标识符 为您的组织服务

   • 安全包含在客户端代码中
   • 用于公共内容终点
   • 基于 API 密钥的后端验证和费率限制
   • 没有有效的 API 密钥, 请求返回 401

2. 认证托肯 (通过Auth0): A 隐藏 JWT 标志

   • 由 SDK 自动管理
   • 仅供成员使用的内容和用户数据
   • 从未在客户端代码中曝光

API 密钥保护什么

端点安全

处理错误

import { useNews, isAxCloudError } from '@axcode/axcloud-sdk';

function NewsPage() {
  const { data, error, isError } = useNews();

  if (isError) {
    if (isAxCloudError(error)) {
      switch (error.code) {
        case 'UNAUTHORIZED':
          return <LoginPrompt />;
        case 'NOT_FOUND':
          return <NotFound />;
        default:
          return <Error message={error.message} />;
      }
    }
    return <Error message="Something went wrong" />;
  }

  return <NewsList items={data} />;
}

许可证

内部使用。 联系 Axcode AB 访问 .