instant-cli 1.0.33 → 1.0.34

package/src/index.ts

@@ -36,6 +36,15 @@ import { authOriginAddCmd } from './commands/auth/origin/add.ts';
 import { link } from './logging.ts';
 import { appListCommand } from './commands/app/list.ts';
 import { appDeleteCommand } from './commands/app/delete.ts';
+import { webhooksListCmd } from './commands/webhooks/list.ts';
+import { webhooksAddCmd } from './commands/webhooks/add.ts';
+import { webhooksUpdateCmd } from './commands/webhooks/update.ts';
+import { webhooksDeleteCmd } from './commands/webhooks/delete.ts';
+import { webhooksEnableCmd } from './commands/webhooks/enable.ts';
+import { webhooksDisableCmd } from './commands/webhooks/disable.ts';
+import { webhooksEventsListCmd } from './commands/webhooks/events/list.ts';
+import { webhooksEventsPayloadCmd } from './commands/webhooks/events/payload.ts';
+import { webhooksEventsResendCmd } from './commands/webhooks/events/resend.ts';
 
 export type OptsFromCommand<C> =
   C extends Command<any, infer R, any> ? R : never;
@@ -392,6 +401,239 @@ export const authOriginDeleteDef = authOrigin
     );
   });
 
+const webhooks = program
+  .command('webhook')
+  .description('Manage webhooks for an app');
+
+export const webhooksListDef = webhooks
+  .command('list')
+  .description('List webhooks for an app')
+  .option(
+    '-a --app <app-id>',
+    'App ID to list webhooks for. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .option('--json', 'Enable JSON output')
+  .action((opts) => {
+    return runCommandEffect(
+      webhooksListCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: false,
+          }).pipe(Layer.annotateLogs('silent', !!opts.json)),
+        ),
+      ),
+    );
+  });
+
+export const webhooksAddDef = webhooks
+  .command('add')
+  .description('Add a webhook to an app')
+  .option('--url <url>', 'HTTPS endpoint to deliver events to')
+  .option(
+    '--namespaces <e1,e2>',
+    'Comma-separated list of namespaces to listen on',
+  )
+  .option(
+    '--actions <a1,a2>',
+    'Comma-separated list of actions (create, update, delete)',
+  )
+  .option(
+    '-a --app <app-id>',
+    'App ID to add a webhook to. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .action((opts) => {
+    return runCommandEffect(
+      webhooksAddCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: false,
+          }),
+        ),
+      ),
+    );
+  });
+
+export const webhooksUpdateDef = webhooks
+  .command('update')
+  .description('Update a webhook')
+  .option('--id <webhook-id>', 'Webhook ID to update')
+  .option('--url <url>', 'New HTTPS endpoint')
+  .option('--namespaces <e1,e2>', 'New comma-separated namespaces')
+  .option(
+    '--actions <a1,a2>',
+    'New comma-separated actions (create, update, delete)',
+  )
+  .option(
+    '-a --app <app-id>',
+    'App ID the webhook belongs to. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .action((opts) => {
+    return runCommandEffect(
+      webhooksUpdateCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: false,
+          }),
+        ),
+      ),
+    );
+  });
+
+export const webhooksDeleteDef = webhooks
+  .command('delete')
+  .description('Delete a webhook')
+  .option('--id <webhook-id>', 'Webhook ID to delete')
+  .option(
+    '-a --app <app-id>',
+    'App ID the webhook belongs to. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .action((opts) => {
+    return runCommandEffect(
+      webhooksDeleteCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: false,
+          }),
+        ),
+      ),
+    );
+  });
+
+export const webhooksEnableDef = webhooks
+  .command('enable')
+  .description('Re-enable a disabled webhook')
+  .option('--id <webhook-id>', 'Webhook ID to enable')
+  .option(
+    '-a --app <app-id>',
+    'App ID the webhook belongs to. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .action((opts) => {
+    return runCommandEffect(
+      webhooksEnableCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: false,
+          }),
+        ),
+      ),
+    );
+  });
+
+export const webhooksDisableDef = webhooks
+  .command('disable')
+  .description('Disable an active webhook')
+  .option('--id <webhook-id>', 'Webhook ID to disable')
+  .option('--reason <reason>', 'Human-readable reason stored on the webhook')
+  .option(
+    '-a --app <app-id>',
+    'App ID the webhook belongs to. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .action((opts) => {
+    return runCommandEffect(
+      webhooksDisableCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: false,
+          }),
+        ),
+      ),
+    );
+  });
+
+const webhooksEvents = webhooks
+  .command('event')
+  .description('Inspect and resend webhook events');
+
+export const webhooksEventsListDef = webhooksEvents
+  .command('list')
+  .description('List recent events for a webhook (up to 100, newest first)')
+  .option('--webhook-id <webhook-id>', 'Webhook ID to inspect')
+  .option('--json', 'Enable JSON output')
+  .option(
+    '-a --app <app-id>',
+    'App ID the webhook belongs to. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .action((opts) => {
+    return runCommandEffect(
+      webhooksEventsListCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: false,
+          }).pipe(Layer.annotateLogs('silent', !!opts.json)),
+        ),
+      ),
+    );
+  });
+
+export const webhooksEventsResendDef = webhooksEvents
+  .command('resend')
+  .description('Re-queue a webhook event for delivery')
+  .option('--webhook-id <webhook-id>', 'Webhook ID the event belongs to')
+  .option('--isn <isn>', 'Event ISN to resend')
+  .option(
+    '-a --app <app-id>',
+    'App ID the webhook belongs to. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .action((opts) => {
+    return runCommandEffect(
+      webhooksEventsResendCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: false,
+          }),
+        ),
+      ),
+    );
+  });
+
+export const webhooksEventsPayloadDef = webhooksEvents
+  .command('payload')
+  .description('Print the JSON payload for a webhook event')
+  .option('--webhook-id <webhook-id>', 'Webhook ID the event belongs to')
+  .option('--isn <isn>', 'Event ISN to fetch')
+  .option(
+    '-a --app <app-id>',
+    'App ID the webhook belongs to. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .action((opts) => {
+    return runCommandEffect(
+      webhooksEventsPayloadCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: false,
+          }),
+        ),
+      ),
+    );
+  });
+
 export const initWithoutFilesDef = program
   .command('init-without-files')
   .description('Generate a new app id and admin token pair without any files.')

package/src/layer.ts

@@ -2,11 +2,12 @@ import * as NodeContext from '@effect/platform-node/NodeContext';
 import * as NodeHttpClient from '@effect/platform-node/NodeHttpClient';
 import { Cause, Effect, Layer, ManagedRuntime } from 'effect';
 import { UnknownException } from 'effect/Cause';
+import { inspect } from 'node:util';
 import chalk from 'chalk';
 import { AuthTokenLive } from './context/authToken.ts';
 import { CurrentAppLive } from './context/currentApp.ts';
 import { GlobalOptsLive } from './context/globalOpts.ts';
-import { PlatformApi } from './context/platformApi.ts';
+import { PlatformApi, PlatformApiError } from './context/platformApi.ts';
 import {
   PACKAGE_ALIAS_AND_FULL_NAMES,
   ProjectInfoLive,
@@ -21,6 +22,19 @@ import { RequestError } from '@effect/platform/HttpClientError';
 
 const runtime = ManagedRuntime.make(SimpleLogLayer);
 
+// Best-effort stringification for unknown error causes. Tries JSON first
+// (compact, readable) and falls back to util.inspect for circular refs or
+// values JSON can't serialize (functions, BigInt, etc.).
+function serializeCause(cause: unknown): string {
+  try {
+    const json = JSON.stringify(cause);
+    if (json !== undefined) return json;
+  } catch {
+    // fall through
+  }
+  return inspect(cause, { depth: 2, breakLength: Infinity });
+}
+
 export const runCommandEffect = <A, E, R extends never>(
   effect: Effect.Effect<A, E, R>,
 ): Promise<A> => runtime.runPromise(effect.pipe(printRedErrors) as any);
@@ -48,6 +62,24 @@ export const printRedErrors = Effect.catchAllCause((cause) =>
       return process.exit(1);
     }
 
+    // Surface server-side validation messages instead of dumping a stack with
+    // the useful detail buried in [cause].
+    if (theError instanceof PlatformApiError) {
+      const cause = theError.cause;
+      const causeMessage =
+        cause instanceof Error
+          ? cause.message
+          : cause != null
+            ? serializeCause(cause)
+            : '';
+      yield* Effect.logError(
+        causeMessage
+          ? `${theError.message}: ${causeMessage}`
+          : theError.message,
+      );
+      return process.exit(1);
+    }
+
     // Special error handling for specific error types
     if (theError instanceof InstantHttpError) {
       if (theError?.message) {

package/src/lib/webhooks.ts

@@ -0,0 +1,127 @@
+import { Effect } from 'effect';
+import {
+  PlatformApi as InstantPlatformApi,
+  type WebhookAction,
+  type WebhookEventInfo,
+  type WebhooksManager,
+} from '@instantdb/platform';
+import { AuthToken } from '../context/authToken.ts';
+import { CurrentApp } from '../context/currentApp.ts';
+import { PlatformApiError } from '../context/platformApi.ts';
+import { BadArgsError } from '../errors.ts';
+import { getBaseUrl } from './http.ts';
+
+const getAuthedPlatformApi = Effect.gen(function* () {
+  const apiURI = yield* getBaseUrl;
+  const authToken = yield* AuthToken;
+  const token = yield* authToken.getAuthToken;
+  return new InstantPlatformApi({ apiURI, auth: { token } });
+});
+
+export const WEBHOOK_ACTIONS: readonly WebhookAction[] = [
+  'create',
+  'update',
+  'delete',
+] as const;
+
+export const useWebhooksManager = <R>(
+  fun: (manager: WebhooksManager<any>) => Promise<R>,
+  errorMessage?: string,
+) =>
+  Effect.gen(function* () {
+    const api = yield* getAuthedPlatformApi;
+    const { appId } = yield* CurrentApp;
+    return yield* Effect.tryPromise({
+      try: () => fun(api.webhooks(appId).manager),
+      catch: (e) =>
+        new PlatformApiError({
+          message: errorMessage ?? 'Error using webhooks api',
+          cause: e,
+        }),
+    });
+  });
+
+/**
+ * Yields a `WebhooksManager` instance scoped to the current app. Use when you
+ * need to hold on to the manager outside an Effect (e.g. to call from inside
+ * an async UI callback).
+ */
+export const buildWebhooksManager = Effect.gen(function* () {
+  const api = yield* getAuthedPlatformApi;
+  const { appId } = yield* CurrentApp;
+  return api.webhooks(appId).manager;
+});
+
+/**
+ * Fetches the app's schema and returns the sorted list of namespace names. Returns
+ * `null` if the schema can't be fetched (network, auth, missing app, etc.) so
+ * callers can fall back to a plain text prompt.
+ */
+export const getRemoteNamespaces = Effect.gen(function* () {
+  const api = yield* getAuthedPlatformApi;
+  const { appId } = yield* CurrentApp;
+  const result = yield* Effect.tryPromise(() => api.getSchema(appId)).pipe(
+    Effect.orElseSucceed(() => null),
+  );
+  if (!result) return null;
+  const entities = result.schema?.entities ?? {};
+  return Object.keys(entities).sort();
+});
+
+/**
+ * Pages through `manager.listEvents` until we have `limit` events or the server
+ * runs out. Returns the events in their natural (newest-first) order.
+ */
+export const fetchRecentEvents = (webhookId: string, limit: number) =>
+  Effect.gen(function* () {
+    const collected: WebhookEventInfo[] = [];
+    let after: string | undefined;
+    while (collected.length < limit) {
+      const page = yield* useWebhooksManager(
+        (m) => m.listEvents(webhookId, after ? { after } : undefined),
+        'Error listing webhook events',
+      );
+      collected.push(...page.events);
+      if (!page.pageInfo.hasNextPage || !page.pageInfo.endCursor) break;
+      after = page.pageInfo.endCursor;
+    }
+    return collected.slice(0, limit);
+  });
+
+const splitCsv = (s: string) =>
+  s
+    .split(',')
+    .map((t) => t.trim())
+    .filter((t) => t.length > 0);
+
+export const parseNamespaces = (raw: string | undefined) =>
+  Effect.gen(function* () {
+    if (raw === undefined) return undefined;
+    const namespaces = splitCsv(raw);
+    if (namespaces.length === 0) {
+      return yield* BadArgsError.make({
+        message: '--namespaces must include at least one namespace',
+      });
+    }
+    return namespaces;
+  });
+
+export const parseActions = (raw: string | undefined) =>
+  Effect.gen(function* () {
+    if (raw === undefined) return undefined;
+    const tokens = splitCsv(raw);
+    if (tokens.length === 0) {
+      return yield* BadArgsError.make({
+        message: '--actions must include at least one action',
+      });
+    }
+    const invalid = tokens.filter(
+      (t): t is string => !WEBHOOK_ACTIONS.includes(t as WebhookAction),
+    );
+    if (invalid.length > 0) {
+      return yield* BadArgsError.make({
+        message: `Invalid action${invalid.length === 1 ? '' : 's'}: ${invalid.join(', ')}. Must be one of: ${WEBHOOK_ACTIONS.join(', ')}`,
+      });
+    }
+    return tokens as WebhookAction[];
+  });