@primstack/cli 0.0.1

package/dist/integrations/search/providers/meilisearch/templates/src/search/index.ts.template

@@ -0,0 +1,49 @@
+import { MeiliSearch } from 'meilisearch';
+import type { SearchDocument, SearchOptions, SearchResult } from './types.js';
+
+export const client = new MeiliSearch({
+  host: process.env.MEILISEARCH_URL || 'http://localhost:7700',
+  apiKey: process.env.MEILISEARCH_API_KEY || '',
+});
+
+export function getIndex(name: string) {
+  return client.index(name);
+}
+
+export async function addDocuments<T extends SearchDocument>(
+  indexName: string,
+  documents: T[],
+): Promise<void> {
+  const index = client.index(indexName);
+  await index.addDocuments(documents);
+}
+
+export async function search<T extends SearchDocument>(
+  indexName: string,
+  query: string,
+  options?: SearchOptions,
+): Promise<SearchResult<T>> {
+  const index = client.index(indexName);
+  const result = await index.search(query, {
+    limit: options?.limit ?? 20,
+    offset: options?.offset,
+    filter: options?.filter,
+    sort: options?.sort,
+  });
+  return {
+    hits: result.hits as T[],
+    totalHits: result.estimatedTotalHits ?? result.hits.length,
+    query,
+    processingTimeMs: result.processingTimeMs,
+  };
+}
+
+export async function deleteDocuments(
+  indexName: string,
+  ids: (string | number)[],
+): Promise<void> {
+  const index = client.index(indexName);
+  await index.deleteDocuments(ids);
+}
+
+export type { SearchDocument, SearchOptions, SearchResult } from './types.js';

package/dist/integrations/search/providers/meilisearch/templates/src/search/types.ts.template

@@ -0,0 +1,18 @@
+export interface SearchDocument {
+  id: string | number;
+  [key: string]: unknown;
+}
+
+export interface SearchOptions {
+  limit?: number;
+  offset?: number;
+  filter?: string;
+  sort?: string[];
+}
+
+export interface SearchResult<T = SearchDocument> {
+  hits: T[];
+  totalHits: number;
+  query: string;
+  processingTimeMs: number;
+}

package/dist/integrations/search/providers/typesense/templates/src/search/index.ts.template

@@ -0,0 +1,71 @@
+import Typesense from 'typesense';
+import type { SearchDocument, SearchOptions, SearchResult, CollectionSchema } from './types.js';
+
+const url = new URL(process.env.TYPESENSE_URL || 'http://localhost:8108');
+
+export const client = new Typesense.Client({
+  nodes: [
+    {
+      host: url.hostname,
+      port: Number(url.port) || 8108,
+      protocol: url.protocol.replace(':', ''),
+    },
+  ],
+  apiKey: process.env.TYPESENSE_API_KEY || '',
+});
+
+export function getCollection(name: string) {
+  return client.collections(name);
+}
+
+/**
+ * Create a collection if it doesn't already exist.
+ * Must be called before addDocuments for new collections.
+ */
+export async function ensureCollection(schema: CollectionSchema): Promise<void> {
+  try {
+    await client.collections(schema.name).retrieve();
+  } catch {
+    await client.collections().create(schema);
+  }
+}
+
+export async function addDocuments<T extends SearchDocument>(
+  collectionName: string,
+  documents: T[],
+): Promise<void> {
+  await client.collections(collectionName).documents().import(documents, { action: 'upsert' });
+}
+
+export async function search<T extends SearchDocument>(
+  collectionName: string,
+  query: string,
+  options?: SearchOptions,
+): Promise<SearchResult<T>> {
+  const start = Date.now();
+  const result = await client.collections(collectionName).documents().search({
+    q: query,
+    query_by: options?.queryBy || 'title',
+    per_page: options?.limit ?? 20,
+    page: options?.offset ? Math.floor(options.offset / (options?.limit ?? 20)) + 1 : 1,
+    filter_by: options?.filter,
+    sort_by: options?.sort?.join(','),
+  });
+  return {
+    hits: (result.hits ?? []).map((h) => h.document as T),
+    totalHits: result.found ?? 0,
+    query,
+    processingTimeMs: Date.now() - start,
+  };
+}
+
+export async function deleteDocuments(
+  collectionName: string,
+  ids: (string | number)[],
+): Promise<void> {
+  await Promise.all(
+    ids.map((id) => client.collections(collectionName).documents(String(id)).delete()),
+  );
+}
+
+export type { SearchDocument, SearchOptions, SearchResult, CollectionSchema } from './types.js';

package/dist/integrations/search/providers/typesense/templates/src/search/types.ts.template

@@ -0,0 +1,35 @@
+export interface SearchDocument {
+  id: string | number;
+  [key: string]: unknown;
+}
+
+export interface SearchOptions {
+  limit?: number;
+  offset?: number;
+  filter?: string;
+  sort?: string[];
+  /** Comma-separated field names to search (required for Typesense, e.g. 'title,body') */
+  queryBy?: string;
+}
+
+export interface SearchResult<T = SearchDocument> {
+  hits: T[];
+  totalHits: number;
+  query: string;
+  processingTimeMs: number;
+}
+
+export interface CollectionSchema {
+  name: string;
+  fields: CollectionField[];
+  default_sorting_field?: string;
+}
+
+export interface CollectionField {
+  name: string;
+  type: 'string' | 'int32' | 'int64' | 'float' | 'bool' | 'string[]' | 'int32[]' | 'int64[]' | 'float[]' | 'bool[]' | 'auto';
+  facet?: boolean;
+  optional?: boolean;
+  index?: boolean;
+  sort?: boolean;
+}

package/dist/integrations/storage/providers/local/templates/src/storage/index.ts.template

@@ -0,0 +1,69 @@
+import fs from 'fs-extra';
+import path from 'path';
+import type { UploadOptions, StorageObject } from './types.js';
+
+const STORAGE_ROOT = process.env.STORAGE_PATH || './uploads';
+
+function resolve(bucket?: string, key?: string): string {
+  const parts = [STORAGE_ROOT];
+  if (bucket) parts.push(bucket);
+  if (key) parts.push(key);
+  const resolved = path.resolve(...parts);
+  const root = path.resolve(STORAGE_ROOT);
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+    throw new Error('Path traversal detected');
+  }
+  return resolved;
+}
+
+export async function uploadFile(options: UploadOptions): Promise<{ key: string }> {
+  const filePath = resolve(options.bucket, options.key);
+  await fs.ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, options.body);
+  return { key: options.key };
+}
+
+export async function downloadFile(key: string, bucket?: string): Promise<Buffer> {
+  const filePath = resolve(bucket, key);
+  return fs.readFile(filePath);
+}
+
+export async function deleteFile(key: string, bucket?: string): Promise<void> {
+  const filePath = resolve(bucket, key);
+  await fs.remove(filePath);
+}
+
+export async function listFiles(prefix?: string, bucket?: string): Promise<StorageObject[]> {
+  const dir = resolve(bucket);
+  if (!(await fs.pathExists(dir))) return [];
+
+  const entries = await fs.readdir(dir);
+  const results: StorageObject[] = [];
+
+  for (const entry of entries) {
+    if (prefix && !entry.startsWith(prefix)) continue;
+    const filePath = path.join(dir, entry);
+    const stat = await fs.stat(filePath);
+    if (stat.isFile()) {
+      results.push({
+        key: entry,
+        size: stat.size,
+        lastModified: stat.mtime,
+      });
+    }
+  }
+
+  return results;
+}
+
+export async function listBuckets(): Promise<string[]> {
+  await fs.ensureDir(STORAGE_ROOT);
+  const entries = await fs.readdir(STORAGE_ROOT, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+export async function createBucket(name: string): Promise<void> {
+  await fs.ensureDir(resolve(name));
+}
+
+export type { UploadOptions, StorageObject } from './types.js';

package/dist/integrations/storage/providers/local/templates/src/storage/types.ts.template

@@ -0,0 +1,12 @@
+export interface UploadOptions {
+  key: string;
+  body: Buffer | Uint8Array | string;
+  contentType?: string;
+  bucket?: string;
+}
+
+export interface StorageObject {
+  key: string;
+  size: number;
+  lastModified: Date;
+}

package/dist/integrations/storage/providers/r2/templates/src/storage/index.ts.template

@@ -0,0 +1,80 @@
+import {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+  DeleteObjectCommand,
+  ListObjectsV2Command,
+} from '@aws-sdk/client-s3';
+import type { UploadOptions, StorageObject } from './types.js';
+
+const s3 = new S3Client({
+  region: 'auto',
+  endpoint: `https://${process.env.R2_ACCOUNT_ID!}.r2.cloudflarestorage.com`,
+  credentials: {
+    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+  },
+});
+
+const DEFAULT_BUCKET = process.env.R2_BUCKET!;
+
+export async function uploadFile(options: UploadOptions): Promise<{ key: string }> {
+  const bucket = options.bucket || DEFAULT_BUCKET;
+  await s3.send(
+    new PutObjectCommand({
+      Bucket: bucket,
+      Key: options.key,
+      Body: options.body,
+      ContentType: options.contentType,
+    }),
+  );
+  return { key: options.key };
+}
+
+export async function downloadFile(key: string, bucket?: string): Promise<Buffer> {
+  const response = await s3.send(
+    new GetObjectCommand({
+      Bucket: bucket || DEFAULT_BUCKET,
+      Key: key,
+    }),
+  );
+  const bytes = await response.Body!.transformToByteArray();
+  return Buffer.from(bytes);
+}
+
+export async function deleteFile(key: string, bucket?: string): Promise<void> {
+  await s3.send(
+    new DeleteObjectCommand({
+      Bucket: bucket || DEFAULT_BUCKET,
+      Key: key,
+    }),
+  );
+}
+
+export async function listFiles(prefix?: string, bucket?: string): Promise<StorageObject[]> {
+  const response = await s3.send(
+    new ListObjectsV2Command({
+      Bucket: bucket || DEFAULT_BUCKET,
+      Prefix: prefix,
+    }),
+  );
+  return (response.Contents || []).map((obj) => ({
+    key: obj.Key!,
+    size: obj.Size || 0,
+    lastModified: obj.LastModified || new Date(),
+  }));
+}
+
+export async function listBuckets(): Promise<string[]> {
+  throw new Error(
+    'R2 does not support ListBuckets via the S3 API. Use the Cloudflare dashboard or wrangler CLI instead.',
+  );
+}
+
+export async function createBucket(name: string): Promise<void> {
+  throw new Error(
+    `R2 does not support CreateBucket via the S3 API. Use the Cloudflare dashboard or 'wrangler r2 bucket create ${name}'.`,
+  );
+}
+
+export type { UploadOptions, StorageObject } from './types.js';

package/dist/integrations/storage/providers/r2/templates/src/storage/types.ts.template

@@ -0,0 +1,12 @@
+export interface UploadOptions {
+  key: string;
+  body: Buffer | Uint8Array | string;
+  contentType?: string;
+  bucket?: string;
+}
+
+export interface StorageObject {
+  key: string;
+  size: number;
+  lastModified: Date;
+}

package/dist/integrations/storage/providers/s3/templates/src/storage/index.ts.template

@@ -0,0 +1,78 @@
+import {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+  DeleteObjectCommand,
+  ListObjectsV2Command,
+  ListBucketsCommand,
+  CreateBucketCommand,
+} from '@aws-sdk/client-s3';
+import type { UploadOptions, StorageObject } from './types.js';
+
+const s3 = new S3Client({
+  region: process.env.AWS_REGION || 'us-east-1',
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+});
+
+const DEFAULT_BUCKET = process.env.S3_BUCKET!;
+
+export async function uploadFile(options: UploadOptions): Promise<{ key: string }> {
+  const bucket = options.bucket || DEFAULT_BUCKET;
+  await s3.send(
+    new PutObjectCommand({
+      Bucket: bucket,
+      Key: options.key,
+      Body: options.body,
+      ContentType: options.contentType,
+    }),
+  );
+  return { key: options.key };
+}
+
+export async function downloadFile(key: string, bucket?: string): Promise<Buffer> {
+  const response = await s3.send(
+    new GetObjectCommand({
+      Bucket: bucket || DEFAULT_BUCKET,
+      Key: key,
+    }),
+  );
+  const bytes = await response.Body!.transformToByteArray();
+  return Buffer.from(bytes);
+}
+
+export async function deleteFile(key: string, bucket?: string): Promise<void> {
+  await s3.send(
+    new DeleteObjectCommand({
+      Bucket: bucket || DEFAULT_BUCKET,
+      Key: key,
+    }),
+  );
+}
+
+export async function listFiles(prefix?: string, bucket?: string): Promise<StorageObject[]> {
+  const response = await s3.send(
+    new ListObjectsV2Command({
+      Bucket: bucket || DEFAULT_BUCKET,
+      Prefix: prefix,
+    }),
+  );
+  return (response.Contents || []).map((obj) => ({
+    key: obj.Key!,
+    size: obj.Size || 0,
+    lastModified: obj.LastModified || new Date(),
+  }));
+}
+
+export async function listBuckets(): Promise<string[]> {
+  const response = await s3.send(new ListBucketsCommand({}));
+  return (response.Buckets || []).map((b) => b.Name!);
+}
+
+export async function createBucket(name: string): Promise<void> {
+  await s3.send(new CreateBucketCommand({ Bucket: name }));
+}
+
+export type { UploadOptions, StorageObject } from './types.js';

package/dist/integrations/storage/providers/s3/templates/src/storage/types.ts.template

@@ -0,0 +1,12 @@
+export interface UploadOptions {
+  key: string;
+  body: Buffer | Uint8Array | string;
+  contentType?: string;
+  bucket?: string;
+}
+
+export interface StorageObject {
+  key: string;
+  size: number;
+  lastModified: Date;
+}

package/dist/integrations/stripe/templates/api/src/lib/stripe.ts.template

@@ -0,0 +1,259 @@
+/**
+ * Stripe Client
+ *
+ * This module provides a configured Stripe client and helper functions
+ * for common billing operations.
+ */
+
+import Stripe from 'stripe';
+import { stripeConfig } from '../../stripe.config.js';
+
+type StripeEnvironment = 'test' | 'live';
+
+// Get current environment
+const STRIPE_ENV = (process.env.STRIPE_ENV || 'test') as StripeEnvironment;
+
+// Initialize Stripe client
+const credentials = stripeConfig.environments[STRIPE_ENV];
+
+if (!credentials?.secretKey) {
+  throw new Error(
+    `Stripe ${STRIPE_ENV} secret key not configured. ` +
+    `Set STRIPE_${STRIPE_ENV.toUpperCase()}_SECRET_KEY environment variable.`
+  );
+}
+
+export const stripe = new Stripe(credentials.secretKey, {
+  apiVersion: '2024-06-20' as any,
+  typescript: true,
+});
+
+/**
+ * Get the current Stripe environment
+ */
+export function getStripeEnvironment(): StripeEnvironment {
+  return STRIPE_ENV;
+}
+
+/**
+ * Get the publishable key for the current environment
+ */
+export function getPublishableKey(): string {
+  return credentials.publishableKey;
+}
+
+/**
+ * Get the webhook secret for the current environment
+ */
+export function getWebhookSecret(): string {
+  return credentials.webhookSecret;
+}
+
+/**
+ * Get or create a Stripe customer for a user
+ *
+ * IMPORTANT: This function searches by userId metadata to avoid
+ * matching wrong customers when emails are shared or reused.
+ */
+export async function getOrCreateCustomer(
+  userId: string,
+  email: string,
+  name?: string
+): Promise<Stripe.Customer> {
+  // First, search for existing customer by userId metadata
+  // This is the primary lookup to ensure we don't mix up customers
+  const customersByUserId = await stripe.customers.search({
+    query: `metadata['userId']:'${userId}'`,
+    limit: 1,
+  });
+
+  if (customersByUserId.data.length > 0) {
+    const customer = customersByUserId.data[0];
+    // Update email if it changed (but keep userId as-is)
+    if (customer.email !== email) {
+      return stripe.customers.update(customer.id, { email });
+    }
+    return customer;
+  }
+
+  // No customer found by userId - create a new one
+  // Do NOT associate existing email-only customers to avoid billing mix-ups
+  return stripe.customers.create({
+    email,
+    name,
+    metadata: {
+      userId,
+      environment: STRIPE_ENV,
+    },
+  });
+}
+
+/**
+ * Create a checkout session for a subscription
+ */
+export async function createCheckoutSession(options: {
+  customerId: string;
+  priceLookupKey: string;
+  successUrl: string;
+  cancelUrl: string;
+  trialDays?: number;
+  metadata?: Record<string, string>;
+}): Promise<Stripe.Checkout.Session> {
+  const { customerId, priceLookupKey, successUrl, cancelUrl, trialDays, metadata } = options;
+
+  // Get price by lookup key
+  const prices = await stripe.prices.list({
+    lookup_keys: [priceLookupKey],
+    limit: 1,
+  });
+
+  if (prices.data.length === 0) {
+    throw new Error(`Price not found for lookup key: ${priceLookupKey}`);
+  }
+
+  const price = prices.data[0];
+
+  return stripe.checkout.sessions.create({
+    customer: customerId,
+    mode: 'subscription',
+    line_items: [
+      {
+        price: price.id,
+        quantity: 1,
+      },
+    ],
+    success_url: successUrl,
+    cancel_url: cancelUrl,
+    subscription_data: trialDays
+      ? {
+          trial_period_days: trialDays,
+          metadata,
+        }
+      : { metadata },
+    metadata,
+  });
+}
+
+/**
+ * Create a customer portal session
+ */
+export async function createPortalSession(
+  customerId: string,
+  returnUrl: string
+): Promise<Stripe.BillingPortal.Session> {
+  return stripe.billingPortal.sessions.create({
+    customer: customerId,
+    return_url: returnUrl,
+  });
+}
+
+/**
+ * Get a subscription by ID
+ */
+export async function getSubscription(
+  subscriptionId: string
+): Promise<Stripe.Subscription | null> {
+  try {
+    return await stripe.subscriptions.retrieve(subscriptionId);
+  } catch (error) {
+    // Handle Stripe API errors - check for resource not found
+    const stripeError = error as Stripe.errors.StripeError;
+    if (stripeError.type === 'invalid_request_error' && stripeError.code === 'resource_missing') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Cancel a subscription
+ */
+export async function cancelSubscription(
+  subscriptionId: string,
+  immediately = false
+): Promise<Stripe.Subscription> {
+  if (immediately) {
+    return stripe.subscriptions.cancel(subscriptionId);
+  }
+
+  // Cancel at period end
+  return stripe.subscriptions.update(subscriptionId, {
+    cancel_at_period_end: true,
+  });
+}
+
+/**
+ * Update subscription to a new price
+ *
+ * Note: This updates the first subscription item (the main plan).
+ * If the subscription has multiple items (add-ons, metered), they remain unchanged.
+ */
+export async function updateSubscription(
+  subscriptionId: string,
+  newPriceLookupKey: string
+): Promise<Stripe.Subscription> {
+  // Get the subscription
+  const subscription = await stripe.subscriptions.retrieve(subscriptionId);
+
+  // Validate subscription has at least one item
+  const firstItem = subscription.items.data[0];
+  if (!firstItem) {
+    throw new Error(`Subscription ${subscriptionId} has no items to update`);
+  }
+
+  // Get new price by lookup key
+  const prices = await stripe.prices.list({
+    lookup_keys: [newPriceLookupKey],
+    limit: 1,
+  });
+
+  if (prices.data.length === 0) {
+    throw new Error(`Price not found for lookup key: ${newPriceLookupKey}`);
+  }
+
+  const newPrice = prices.data[0];
+
+  // Update only the first subscription item (main plan)
+  return stripe.subscriptions.update(subscriptionId, {
+    items: [
+      {
+        id: firstItem.id,
+        price: newPrice.id,
+      },
+    ],
+    proration_behavior: 'create_prorations',
+  });
+}
+
+/**
+ * Report usage for a meter
+ */
+export async function reportUsage(
+  subscriptionItemId: string,
+  quantity: number,
+  timestamp?: number
+): Promise<Stripe.UsageRecord> {
+  return stripe.subscriptionItems.createUsageRecord(subscriptionItemId, {
+    quantity,
+    timestamp: timestamp || Math.floor(Date.now() / 1000),
+    action: 'increment',
+  });
+}
+
+/**
+ * Construct and verify a webhook event
+ */
+export function constructWebhookEvent(
+  payload: string | Buffer,
+  signature: string
+): Stripe.Event {
+  const webhookSecret = getWebhookSecret();
+
+  if (!webhookSecret) {
+    throw new Error('Webhook secret not configured');
+  }
+
+  return stripe.webhooks.constructEvent(payload, signature, webhookSecret);
+}
+
+export default stripe;