FAQ

General Questions

Do developers need to provide their own servers?

No. Build artifacts are packaged as ZIP files and uploaded to the platform, which handles hosting and distribution.

What frameworks does the SDK support?

The SDK is a framework-agnostic pure JavaScript library. You can use native HTML, React, Vue, Svelte, Angular, or any other framework. The only requirement is that the final output must be a set of static assets with index.html as the entry point.

How do I debug during local development?

const sdk = GeneratorSDK.init({
  appKey: 'app_xxx',
  env: 'test',  // Connect to the test environment API
})

You can use any static server like vite dev or npx serve . to start and debug your application.

Initialization and Login

What if getStatus() returns "not logged in" immediately after init()?

The SDK asynchronously validates the cached token during initialization. Validation might not be complete when init() returns. Use sdk.auth.onChange() to listen for the final login status:

sdk.auth.onChange((status) => {
  if (status.isLogin) {
    // Confirmed login state
  }
})

How do I cancel onChange and other listeners?

All onChange methods return a function to unsubscribe:

const unsub = sdk.auth.onChange(callback)
unsub() // Unsubscribe

What is the username field in user info?

It is userName (not nickname), corresponding to the backend userName field.

Framework Integration

What should I keep in mind when using the SDK with Vue 3?

Use shallowRef + markRaw to prevent Vue from deeply proxying the SDK's internal objects:

import { shallowRef, markRaw } from 'vue'

const sdk = shallowRef(null)
sdk.value = markRaw(GeneratorSDK.init({ appKey: 'app_xxx' }))

Credits and Billing

What is the field name returned by credits.getBalance()?

It returns { quota: number }, not { balance: number }, to stay consistent with the backend interface.

What is the difference between Billing and Credits?

• Billing (Recommended): A high-level wrapper that automatically handles the fallback from free quota to credits. Suitable for standard operations like export and download.
• Credits: Low-level credit operations for custom scenarios requiring direct deduction of specific amounts (e.g., AI generation).

Is the credit check in withBilling synchronous or asynchronous?

Synchronous. withBilling calls billing.check() internally, which uses cached data. Ensure you have called billing.getUsage() at least once before use to load the cache.

Do operations during the free period trigger network requests?

No. billing.consume() returns success directly during the free period without calling the backend.

Deployment and Upload

What are the requirements for the ZIP package?

• The entry file must be index.html (located at the root of the ZIP).
• All static assets must be referenced using relative paths.
• No server-side code is allowed.
• ZIP package size limit: 50MB.

How should first-phase developers define an appKey?

Use a stable generator ID as the appKey. Developers can define this ID themselves, as long as the same generator keeps using the same value.