通过 100 多个技巧的集合学习 Nuxt！
55.5K

planship
@planship/nuxt

用于 Nuxt 应用程序的授权、计量、计划打包和订阅管理。
55 次下载
8 颗星
v0.3.6
pwojnaropwojnaro

planship-nuxt

欢迎使用 @planship/nuxt，一个 Nuxt 模块，它使您的 Nuxt 应用程序能够使用 Planship 进行授权、计量、计划打包和客户/订阅管理。该模块基于 @planship/vue 插件和 @planship/fetch 库。

一个使用此模块的 Nuxt 应用程序的完整工作示例可以在 https://github.com/planship/planship-nuxt-example 找到。

开始使用

使用 npm、yarn 或 pnpm 安装 @planship/nuxt

npm install @planship/nuxt
# or
yarn add @planship/nuxt
# or
pnpm add @planship/nuxt

然后，将 @planship/nuxt 添加到您的 nuxt.config.ts 的 modules 部分

export default defineNuxtConfig({
  modules: ['@planship/nuxt']
})

最后，在 defineNuxtConfig 中或通过环境变量配置您的 Planship 产品 slug 和身份验证凭据。

export default defineNuxtConfig({
  // ...
  planship: {
    productSlug: '<YOUR_PLANSHIP_PRODUCT_SLUG',
    clientId: '<YOUR_PLANSHIP_API_CLIENT_ID>',
    clientSecret: '<YOUR_PLANSHIP_API_CLIENT_SECRET>'
  }
}

配置选项

productSlug

您的 Planship 产品 slug。该 slug 也可以通过 PLANSHIP_PRODUCT_SLUG 环境变量定义。

clientId 和 clientSecret

您的 Planship 身份验证凭据。它们也可以通过 PLANSHIP_API_CLIENT_ID 和 PLANSHIP_API_CLIENT_SECRET 环境变量定义。

用法

组合式函数

@planship/nuxt 模块导出由 @planship/vue 插件实现的两个组合式函数：usePlanshipCustomer 和 usePlanship。@planship/vue 插件是通用模式友好的，这意味着这些组合式函数可以用于服务器端和客户端渲染。

使用授权和其他客户数据 - usePlanshipCustomer

在大多数渲染场景中，您的应用程序需要获取和评估特定客户的 Planship 授权。这可以通过 Planship 插件和 usePlanshipCustomer 函数来完成，该函数为特定客户初始化 Planship API 实例，持续获取他们的 entitlements，并将它们暴露在响应式的 Vue ref 对象中。

下面的示例展示了如何检索客户授权，以及如何使用一个名为 advanced-analytics 的简单布尔功能来有条件地在 Vue 组件内部渲染一个 <NuxtLink> 元素。

<script setup>
  import { usePlanshipCustomer } from '@planship/nuxt'

  const { entitlements } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')
</script>

<template>
  <NuxtLink
    v-if="entitlements['advanced-analytics']"
    to="/analytics"
  >
    Analytics
  </NuxtLink>
</template>

当在客户端使用 usePlanshipCustomer 时，授权会在每次更改时通过 WebSocket 连接自动更新。

在通用渲染模式下使用时，数据以以下方式获取

  1. 插件在服务器上初始化，并获取 Planship 授权和订阅数据，以便用于服务器端渲染。
  2. 插件在客户端使用服务器上已获取的数据进行初始化。
  3. 插件在客户端重新激活自身，并启动一个 WebSocket 连接，以便从 Planship 持续更新授权。

用于 sync 和 async 操作的复合返回值

usePlanshipCustomer 函数返回一个复合结果，它既是一个 promise，也是 promise 解析后的数据对象。这意味着该函数既可以作为同步函数调用，也可以使用 await（或 then/catch 链）作为异步函数调用。

如果您想阻塞代码执行，直到从 Planship API 获取客户授权，请使用 await 调用该函数

const { entitlements } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')

如果您想立即返回并异步获取授权，只需在不使用 await 的情况下调用 usePlanshipCustomer

const { entitlements } = usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')

由于 entitlements 是一个响应式的 Vue Ref 对象，您可以在组件和页面模板中使用它，并让 Nuxt 在获取授权后自动重新渲染。

从 Planship 获取附加数据

您的应用程序可能需要从 Planship 获取额外的客户数据（例如，客户订阅或使用数据）。要完成任何 Planship API 操作，请使用由 usePlanshipCustomer 函数返回的 Planship Customer API 客户端的实例。

下面是一个 Nuxt 设置脚本示例，该脚本使用 Nuxt 的 useAsyncData 检索当前客户的订阅列表。

<script setup>
  import { usePlanshipCustomer } from '@planship/nuxt'

  const { planshipCustomerApiClient } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')

  const { data: subscriptions } = await useAsyncData('subscriptions', async () => {
    return await planshipCustomerApiClient.listSubscriptions()
  })
</script>

强类型授权对象

当使用 usePlanshipCustomer 返回的授权字典时，将其包装在一个具有用于单个杠杆的 getter 的对象中可能很有用。这在像 VS Code 这样的 IDE 中尤其有利，因为它为 entitlements 启用了自动完成功能。

为此，请为您的产品定义一个授权类，并将其传递给 usePlanshipCustomer。

<script setup>
  import { usePlanshipCustomer, EntitlementsBase } from '@planship/nuxt'

  class MyEntitlements extends EntitlementsBase {
    get apiCallsPerMonth(): number {
      return this.entitlementsDict?.['api-calls-per-month'].valueOf()
    }

    get advancedAnalytics(): boolean {
      return this.entitlementsDict?.['advanced-analytics']
    }
  }

  // entitlements is of Ref<MyEntitlements> type
  const { entitlements } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>', MyEntitlements)
</script>

<template>
  <NuxtLink
    v-if="entitlements.advancedAnalytics"
    to="/analytics"
  >
    Analytics
  </NuxtLink>
</template>

使用计划和其他产品数据 - usePlanship

如果当前客户上下文未知，usePlanship 函数可以检索 Planship API 客户端。它公开了与 usePlanshipCustomer 提供的 Planship 客户 API 客户端相同的功能，但所有客户操作（例如，获取授权和订阅）都需要一个 Planship 客户 ID 作为参数。

下面是一个 Nuxt 设置脚本示例，该脚本使用 Nuxt 的 useAsyncData 检索 Planship 计划列表。

<script setup>
  import { usePlanship } from '@planship/nuxt'

  const { planshipApiClient } = usePlanship()

  const { data: plans } = await useAsyncData('plans', async () => {
    return await planshipApiClient.listPlans()
  })
</script>

服务器服务

由于 usePlanshipCustomer 和 usePlanship 组合式函数使用 Vue provide/inject 机制，它们只能在应用程序组件中使用。为了简化在组件代码之外使用 Planship 数据（例如，服务器路由），@planship/nuxt 模块提供了在 #planship/server 别名中可用的 useServerApiClient 服务器服务。

下面是一个 Nuxt API 端点的示例，该端点使用通过 useServerApiClient 服务器服务函数检索的 Planship API 客户端向 Planship API 报告计量使用情况。

import { useServerApiClient } from '#planship/server'

export default defineEventHandler(async (event) => {
  const planship = useServerApiClient()
  const body = await readBody(event)

  // Report usage for api-call metering ID to Planship
  return planship.reportUsage(body.userId, 'api-call', body.count)
})

链接