Building plugins

import type { CMSPlugin } from '@createcms/core';

export function pageViews() {
  return { id: 'pageViews' } satisfies CMSPlugin;
}

import { createCMS } from '@createcms/core';
import { pageViews } from './plugins/page-views';

export const cms = createCMS({
  db,
  collections,
  media,
  plugins: [pageViews()],
});

import { definePluginSchema } from '@createcms/core';

const schema = definePluginSchema()({
  enums: {
    abTestStatus: { values: ['draft', 'running', 'paused', 'completed'] },
  },
  tables: {
    abTests: {
      tableName: 'ab_tests',
      indexPrefix: 'abt',
      columns: {
        id: { type: 'text', primaryKey: true, defaultId: true, defaultIdPrefix: 'abTest' },
        rootId: {
          type: 'text',
          notNull: true,
          references: { table: 'roots', column: 'id', onDelete: 'cascade' },
        },
        status: {
          type: { enum: 'abTestStatus' },
          notNull: true,
          default: { kind: 'literal', value: 'draft' },
        },
        createdAt: { type: 'timestamp', notNull: true, defaultNow: true },
      },
      // Indexes are table-level, keyed by name.
      indexes: {
        rootIdx: { columns: ['rootId'] },
        statusIdx: { columns: ['status'] },
      },
    },
  },
});

import { definePlugin, definePluginSchema } from '@createcms/core';

// Curried: call `definePluginSchema()` (no type arg when you only declare your
// own tables), then pass the schema. Use `definePluginSchema<CoreTables>()` when
// you `extend` core tables so the extend keys are type-checked.
const schema = definePluginSchema()({
  tables: {
    pageViews: {
      tableName: 'page_views',
      indexPrefix: 'pgv',
      columns: {
        // one row per root → rootId is the primary key
        rootId: {
          type: 'text',
          primaryKey: true,
          references: { table: 'roots', column: 'id', onDelete: 'cascade' },
        },
        // `default` is a discriminated union, not a raw scalar.
        count: {
          type: 'integer',
          notNull: true,
          default: { kind: 'literal', value: 0 },
        },
        updatedAt: { type: 'timestamp', notNull: true, defaultNow: true },
      },
    },
  },
});

// `definePlugin` keeps `id` a literal (so `cms.api.pageViews` is a real
// namespace, not a string index signature) and preserves endpoint contributions.
export function pageViews() {
  return definePlugin({ id: 'pageViews', schema });
}

import { createCMSEndpoint, cmsMeta } from '@createcms/core';
import { sql } from 'drizzle-orm';
import * as z from 'zod';

const endpoints = {
  recordView: createCMSEndpoint(
    '/pageViews/recordView',
    {
      method: 'POST',
      body: z.object({ rootId: z.string() }),
      metadata: cmsMeta(
        { $Infer: { body: {} as { rootId: string } } },
        { operation: 'update', scope: 'system', permissionResource: 'pageViews' },
      ),
    },
    async (reqCtx) => {
      const { db } = reqCtx.context;
      const { rootId } = reqCtx.body;
      await db.execute(sql`
        insert into "cms"."page_views" ("root_id", "count") values (${rootId}, 1)
        on conflict ("root_id") do update set
          "count" = "cms"."page_views"."count" + 1,
          "updated_at" = now()
      `);
      return {};
    },
  ),

  getViews: createCMSEndpoint(
    '/pageViews/getViews',
    {
      method: 'GET',
      query: z.object({ rootId: z.string() }),
      metadata: cmsMeta(
        { $Infer: { query: {} as { rootId: string } } },
        { operation: 'read', scope: 'system', permissionResource: 'pageViews' },
      ),
    },
    async (reqCtx) => {
      const { db } = reqCtx.context;
      const rows = await db.execute<{ count: number }>(sql`
        select "count" from "cms"."page_views" where "root_id" = ${reqCtx.query.rootId}
      `);
      return { count: rows[0]?.count ?? 0 };
    },
  ),
};

import { APIError } from 'better-call';

const $ERROR_CODES = {
  PAGE_VIEWS_ROOT_NOT_FOUND: { status: 404, message: 'Root not found' },
} as const;

// inside a handler:
throw new APIError(404, {
  code: 'PAGE_VIEWS_ROOT_NOT_FOUND',
  message: $ERROR_CODES.PAGE_VIEWS_ROOT_NOT_FOUND.message,
});

hooks: {
  after: [
    {
      action: 'archiveRoot',
      handler: async (ctx) => {
        // ctx.action, ctx.collection, ctx.db, ctx.input, ctx.scope
        await ctx.db.execute(
          sql`delete from "cms"."page_views" where "root_id" = ${ctx.input.rootId}`,
        );
      },
    },
  ],
}

import type { CMSPlugin, ScopeConditionFactory } from '@createcms/core';
import { sql } from 'drizzle-orm';

init(_ctx) {
  // Runs once per request; `mw` is your authMiddleware's result.
  const factory: ScopeConditionFactory = (mw) => {
    const tenantSlug = (mw as { tenantSlug?: string }).tenantSlug;
    return {
      roots: {
        where: sql`"cms"."roots"."tenant_slug" = ${tenantSlug}`,
        insertColumns: { tenant_slug: tenantSlug },
      },
      // …assets, redirects, templates, variables, etc.
    };
  };
  return { context: { scopeConditions: [factory] } };
}

collectionEndpoints: (collection, ctx) => ({
  createTranslation: createCMSEndpoint(/* … */),
  listTranslations: createCMSEndpoint(/* … */),
}),

async onRequest(request, ctx) {
  const url = new URL(request.url);
  // The A/B plugin caps its one anonymous write path, POST /abTest/trackEvent.
  if (request.method === 'POST' && url.pathname.endsWith('/abTest/trackEvent')) {
    const limited = await rateLimit(request);
    if (limited) return { response: limited }; // 429, pipeline stops here
  }
}

middlewares: [{ path: '/pageViews/*', middleware: myMiddleware }],

import * as z from 'zod';

// on the plugin object:
notificationTypes: {
  abTestWinner: z.object({ testId: z.string(), variant: z.string() }),
},

import type { CMSClientPlugin } from '@createcms/core';

export function pageViewsClient(): CMSClientPlugin {
  return {
    id: 'pageViews',
    getActions: ($fetch) => ({
      recordView: (rootId: string) =>
        $fetch('/pageViews/recordView', { method: 'POST', body: { rootId } }),
    }),
    $ERROR_CODES: { PAGE_VIEWS_ROOT_NOT_FOUND: { status: 404, message: 'Root not found' } },
  };
}

import { createCMSClient } from '@createcms/core/react';
import { pageViewsClient } from './plugins/page-views-client';

export const client = createCMSClient<typeof cms>()({
  baseURL: '/api/cms',
  plugins: [pageViewsClient()],
});

// fully typed:
await client.pageViews.getViews({ query: { rootId } }); // from the server endpoint
client.recordView(rootId); // from getActions