@razorsoft/causewise
v0.1.2
Published
Server-side TypeScript client for the CauseWise management and analytics API.
Downloads
351
Maintainers
Readme
CauseWise server SDK
@razorsoft/causewise is a server-side client for the CauseWise management and analytics API. It sends your workspace API key to CauseWise and returns the JSON the API already produces. It does not include the analytics engine, database, billing rules, or any other CauseWise service.
npm install @razorsoft/causewiseDo not import it from browser code. The package browser export throws.
Requirements
Premium API access needs all of the following. CauseWise checks them on the server. The SDK cannot grant access.
- A workspace API key (
cw_api_…), created in CauseWise under Settings → API keys. - An active eligible subscription: Pro, Team, or Enterprise with status
active,trialing, or unset. The free plan, and a paid plan that iscanceled,past_due, orunpaid, receives402 subscription_required. There is no extra grace period. - The scopes the call needs.
- A site that belongs to the key's workspace. Another workspace's site id returns
404.
Tracking collection, the public tracking key, the dashboard, and the WordPress snippet do not use this SDK and stay available on the free plan.
Scopes
| Call | Scope |
| --- | --- |
| sites.list, sites.get | sites:read |
| analytics.summary, analytics.overview, analytics.trackingStatus, analytics.recentEvents | analytics:read |
| goals.list, goals.analytics | goals:read |
| funnels.list, funnels.analytics | funnels:read |
Write scopes are not used by this SDK. A write scope does not include the matching read scope.
Configuration
import { CauseWise } from "@razorsoft/causewise";
const causewise = new CauseWise({
apiKey: process.env.CAUSEWISE_API_KEY!,
// Optional. Defaults to https://causewise.io.
baseUrl: process.env.CAUSEWISE_API_BASE_URL,
});Read the key from the server environment or a secret store. Do not put it in NEXT_PUBLIC_ variables, client components, or the browser bundle.
Fetch analytics
const analytics = await causewise.analytics.summary({
siteId: "site_123",
range: "7d",
});
const overview = await causewise.analytics.overview({
siteId: "site_123",
range: "7d",
});
const goals = await causewise.goals.list("site_123");
const goal = await causewise.goals.analytics({
siteId: "site_123",
goalId: goals[0]?.id ?? "goal_123",
range: "7d",
});
const funnels = await causewise.funnels.list("site_123");
const funnel = await causewise.funnels.analytics({
siteId: "site_123",
funnelId: funnels[0]?.id ?? "funnel_123",
range: "7d",
});range is today, 7d, or 30d. The API may shorten a range to the workspace retention window. overview.trend counts every event in each bucket. It is not a pageview series. funnel.conversionWindow is a number of seconds. Goal analytics conversionRate is the unique-visitor rate. The summary goal rate is the dashboard rollup.
Also available:
causewise.sites.list()andcausewise.sites.get(siteId)causewise.analytics.overview({ siteId, range })for the traffic trend. Each trend point counts every event in that bucket, not pageviews alone.causewise.analytics.trackingStatus(siteId)causewise.analytics.recentEvents({ siteId, limit })causewise.goals.list(siteId)andcausewise.goals.analytics({ siteId, goalId, range })causewise.funnels.list(siteId)andcausewise.funnels.analytics({ siteId, funnelId, range })
Next.js server component
The server component calls CauseWise. The client component receives only the result.
import { CauseWise } from "@razorsoft/causewise";
import { Stats } from "./stats";
export default async function Page() {
const causewise = new CauseWise({ apiKey: process.env.CAUSEWISE_API_KEY! });
const summary = await causewise.analytics.summary({
siteId: process.env.CAUSEWISE_SITE_ID!,
range: "7d",
});
return <Stats pageviews={summary.pageviews} sessions={summary.sessions} />;
}"use client";
export function Stats({ pageviews, sessions }: { pageviews: number; sessions: number }) {
return (
<p>
{pageviews} pageviews, {sessions} sessions
</p>
);
}Secure route handler
Use this when the browser needs to refresh analytics. The handler must check the signed-in user before it calls CauseWise. Do not expose a public route that forwards the management key.
import { auth } from "@clerk/nextjs/server";
import { CauseWise, CauseWiseError } from "@razorsoft/causewise";
import { NextResponse } from "next/server";
export async function GET() {
const { userId } = await auth();
if (!userId) return NextResponse.json({ error: "Sign in required." }, { status: 401 });
const causewise = new CauseWise({ apiKey: process.env.CAUSEWISE_API_KEY! });
try {
const summary = await causewise.analytics.summary({
siteId: process.env.CAUSEWISE_SITE_ID!,
range: "7d",
});
return NextResponse.json({ pageviews: summary.pageviews, sessions: summary.sessions });
} catch (error) {
if (error instanceof CauseWiseError) {
return NextResponse.json({ error: error.message }, { status: error.status || 502 });
}
throw error;
}
}The browser calls /api/analytics on your application. It never sees CAUSEWISE_API_KEY.
Errors
Failures throw CauseWiseError with status, code, message, and retryAfterSeconds.
| Code | Status | Meaning |
| --- | --- | --- |
| unauthorized | 401 | Missing, invalid, revoked, or expired key. |
| forbidden | 403 | The key is missing the required scope. |
| subscription_required | 402 | The workspace is not on an eligible paid subscription. |
| rate_limited | 429 | More than 120 requests in a minute. Wait retryAfterSeconds. |
| not_found | 404 | The site, goal, or funnel is not in this workspace. |
| network_error | 0 | CauseWise could not be reached. |
Security
- Import the SDK from server code only. The package
browserexport throws, and constructingCauseWisethrows whenwindowexists. - The SDK sends the key as
Authorization: Bearerand does not write it to errors. - Pass only the fields you want to render into client components.
- Your application decides which of its users may see a site. CauseWise only checks the workspace key, subscription, scopes, and site ownership.
Component data
Future components should use the exported contracts (CauseWiseDashboardData, CauseWiseTrafficChartData, and the related types). COMPONENT_DATA_GAPS lists metrics the API does not provide. The traffic chart uses analytics.overview().trend. Each point counts every event in that bucket, not pageviews alone. The summary does not include a time series.
License
The CauseWise Client License lets you install this package, use it in commercial applications, modify the client code, and redistribute it as part of a compiled application. It does not include the CauseWise service or analytics engine. See LICENSE.
