@vinadesignstore/core-client

Public SDK for the VNDS central auth and shared settings platform.

The package is public so satellite apps can install it easily, but the issued apiKey must stay server-side.

Install

pnpm add @vinadesignstore/core-client

Environment

VNDS_AUTH_BASE_URL=https://auth.vinadesignstore.com
VNDS_CORE_APP_ID=your-app-id
VNDS_CORE_API_KEY=your-app-api-key

Create a client

import { createVndsCoreClient } from "@vinadesignstore/core-client";

export const core = createVndsCoreClient({
  baseUrl: process.env.VNDS_AUTH_BASE_URL!,
  appId: process.env.VNDS_CORE_APP_ID!,
  apiKey: process.env.VNDS_CORE_API_KEY!,
});

OAuth helpers

Typical server-driven login flow:

const pkce = await core.auth.generatePkcePair();

const authorizeUrl = core.auth.buildAuthorizeUrl({
  appId: process.env.VNDS_CORE_APP_ID!,
  redirectUri: "https://store.example.com/auth/callback",
  state: "csrf-token",
  codeChallenge: pkce.codeChallenge,
});

const tokens = await core.auth.exchangeAuthorizationCode({
  code: "callback-code",
  codeVerifier: pkce.codeVerifier,
  redirectUri: "https://store.example.com/auth/callback",
});

const user = await core.auth.fetchUserInfo(tokens.access_token);

Expected OAuth endpoints:

• /api/auth/oauth2/authorize
• /api/auth/oauth2/token
• /api/auth/oauth2/userinfo

Useful claims returned by the central auth server include:

• onboarding_complete
• password_set
• discord_connected
• discord_member
• discord_user_id
• discord_role_ids
• discord_member_guild_ids
• discord_guild_memberships
• app_roles
• roles_last_synced_at

discord_member means the user is currently a member of at least one configured VNDS Discord server. Use discord_member_guild_ids or discord_guild_memberships when your app needs per-server details.

Shared settings helpers

await core.settings.set("storefront", "branding", {
  logoUrl: "https://cdn.example.com/logo.svg",
  accent: "#7c3aed",
});

const item = await core.settings.get("storefront", "branding");
const list = await core.settings.list("storefront");
await core.settings.delete("storefront", "branding");

Expected config endpoints:

• /api/configs/[namespace]
• /api/configs/[namespace]/[key]

Security guidance

• keep VNDS_CORE_API_KEY on the server only
• generatePkcePair and buildAuthorizeUrl can be used for browser redirects if needed
• exchangeAuthorizationCode, getClientCredentialsToken, and all settings helpers should run server-side

Publish

Before the first publish:

pnpm install
pnpm --filter @vinadesignstore/core-client build
pnpm --filter @vinadesignstore/core-client pack:dry-run

Then log in to npm and publish the package publicly:

npm login
pnpm publish:sdk

Notes:

• the package already sets publishConfig.access=public
• pnpm publish:sdk uses --no-git-checks, which is handy while you are iterating locally
• if you want a stricter release process later, switch to tags or Changesets before publishing updates