@loopstack/observability-examples 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+---
+title: Observability Examples
+description: Workflow examples for observability in Loopstack — opt-in quota tracking and enforcement
+---
+
+# @loopstack/observability-examples
+
+> Observability workflow examples for the [Loopstack](https://loopstack.ai) automation framework.
+
+Workflow examples for tracking and enforcing operational limits.
+
+## Install as Source (Recommended)
+
+```bash
+npx giget@latest gh:loopstack-ai/loopstack/registry/examples/observability-examples src/observability-examples
+```
+
+Register the module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { LoopstackModule } from '@loopstack/loopstack-module';
+import { ObservabilityExamplesModule } from './observability-examples/observability-examples.module';
+
+@Module({
+  imports: [LoopstackModule.forRoot(), ObservabilityExamplesModule],
+})
+export class AppModule {}
+```
+
+## Install as a Dependency
+
+```bash
+npm install @loopstack/observability-examples
+```
+
+```typescript
+import { ObservabilityExamplesModule } from '@loopstack/observability-examples';
+```
+
+## Examples
+
+| Example         | Studio title                    | Description                                                             |
+| --------------- | ------------------------------- | ----------------------------------------------------------------------- |
+| [Quota](#quota) | `Observability - Quota Example` | Check + report usage with `@loopstack/quota`, Redis-backed when enabled |
+
+---
+
+## Quota
+
+Demonstrates opt-in quota tracking using `@loopstack/quota`:
+
+1. `quotaClient.checkQuota(userId, quotaType)` — verify available budget
+2. Perform the (placeholder) operation if allowed
+3. `quotaClient.report(userId, quotaType, amount)` — charge against the quota
+
+When `QuotaModule.forRoot({ enabled: false })`, both calls no-op. Set `enabled: true` plus Redis connection options to enforce real limits.
+
+### Files
+
+- `quota-example.workflow.ts` — workflow class
+
+## About
+
+Author: [Jakob Klippel](https://www.linkedin.com/in/jakob-klippel/)
+
+License: MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './observability-examples.module';
+export * from './workflows/quota/quota-example.workflow';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iCAAiC,CAAC;AAChD,cAAc,0CAA0C,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./observability-examples.module"), exports);
+__exportStar(require("./workflows/quota/quota-example.workflow"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kEAAgD;AAChD,2EAAyD"}

package/dist/observability-examples.module.d.ts

@@ -0,0 +1,3 @@
+export declare class ObservabilityExamplesModule {
+}
+//# sourceMappingURL=observability-examples.module.d.ts.map

package/dist/observability-examples.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-examples.module.d.ts","sourceRoot":"","sources":["../src/observability-examples.module.ts"],"names":[],"mappings":"AAKA,qBASa,2BAA2B;CAAG"}

package/dist/observability-examples.module.js

@@ -0,0 +1,28 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservabilityExamplesModule = void 0;
+const common_1 = require("@nestjs/common");
+const common_2 = require("@loopstack/common");
+const quota_1 = require("@loopstack/quota");
+const quota_example_workflow_1 = require("./workflows/quota/quota-example.workflow");
+let ObservabilityExamplesModule = class ObservabilityExamplesModule {
+};
+exports.ObservabilityExamplesModule = ObservabilityExamplesModule;
+exports.ObservabilityExamplesModule = ObservabilityExamplesModule = __decorate([
+    (0, common_2.StudioApp)({
+        title: 'Observability Examples',
+        workflows: [quota_example_workflow_1.QuotaExampleWorkflow],
+    }),
+    (0, common_1.Module)({
+        imports: [quota_1.QuotaModule.forRoot({ enabled: false })],
+        providers: [quota_example_workflow_1.QuotaExampleWorkflow],
+        exports: [quota_example_workflow_1.QuotaExampleWorkflow],
+    })
+], ObservabilityExamplesModule);
+//# sourceMappingURL=observability-examples.module.js.map

package/dist/observability-examples.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-examples.module.js","sourceRoot":"","sources":["../src/observability-examples.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AACxC,8CAA8C;AAC9C,4CAA+C;AAC/C,qFAAgF;AAWzE,IAAM,2BAA2B,GAAjC,MAAM,2BAA2B;CAAG,CAAA;AAA9B,kEAA2B;sCAA3B,2BAA2B;IATvC,IAAA,kBAAS,EAAC;QACT,KAAK,EAAE,wBAAwB;QAC/B,SAAS,EAAE,CAAC,6CAAoB,CAAC;KAClC,CAAC;IACD,IAAA,eAAM,EAAC;QACN,OAAO,EAAE,CAAC,mBAAW,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,SAAS,EAAE,CAAC,6CAAoB,CAAC;QACjC,OAAO,EAAE,CAAC,6CAAoB,CAAC;KAChC,CAAC;GACW,2BAA2B,CAAG"}

package/dist/workflows/quota/quota-example.workflow.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { BaseWorkflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { QuotaClientService } from '@loopstack/quota';
+interface QuotaExampleState {
+    hasQuota?: boolean;
+    used?: number;
+    limit?: number;
+}
+declare const QuotaExampleArgsSchema: z.ZodObject<{
+    quotaType: z.ZodDefault<z.ZodString>;
+    reportAmount: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type QuotaExampleArgs = z.infer<typeof QuotaExampleArgsSchema>;
+export declare class QuotaExampleWorkflow extends BaseWorkflow<QuotaExampleArgs> {
+    private readonly quotaClient;
+    constructor(quotaClient: QuotaClientService);
+    checkQuota(_state: QuotaExampleState, ctx: RunContext<QuotaExampleArgs>): Promise<void>;
+    reportUsage(_state: QuotaExampleState, ctx: RunContext<QuotaExampleArgs>): Promise<void>;
+}
+export {};
+//# sourceMappingURL=quota-example.workflow.d.ts.map

package/dist/workflows/quota/quota-example.workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/quota/quota-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAA0C,MAAM,mBAAmB,CAAC;AACzF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,UAAU,iBAAiB;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,QAAA,MAAM,sBAAsB;;;iBAG1B,CAAC;AAEH,KAAK,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE/D,qBAMa,oBAAqB,SAAQ,YAAY,CAAC,gBAAgB,CAAC;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,kBAAkB;IAKtD,UAAU,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,UAAU,CAAC,gBAAgB,CAAC;IAkBvE,WAAW,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,UAAU,CAAC,gBAAgB,CAAC;CAkB/E"}

package/dist/workflows/quota/quota-example.workflow.js

@@ -0,0 +1,78 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotaExampleWorkflow = void 0;
+const zod_1 = require("zod");
+const common_1 = require("@loopstack/common");
+const quota_1 = require("@loopstack/quota");
+const QuotaExampleArgsSchema = zod_1.z.object({
+    quotaType: zod_1.z.string().default('ai_generate_text'),
+    reportAmount: zod_1.z.number().default(1000),
+});
+let QuotaExampleWorkflow = class QuotaExampleWorkflow extends common_1.BaseWorkflow {
+    quotaClient;
+    constructor(quotaClient) {
+        super();
+        this.quotaClient = quotaClient;
+    }
+    async checkQuota(_state, ctx) {
+        const result = await this.quotaClient.checkQuota(ctx.userId ?? 'anonymous', ctx.args.quotaType);
+        const allowed = !result.exceeded;
+        await this.documentStore.save(common_1.MarkdownDocument, {
+            markdown: [
+                '## Quota Check',
+                '',
+                `- Allowed: \`${allowed}\``,
+                `- Used: \`${result.used}\``,
+                `- Limit: \`${result.limit}\``,
+            ].join('\n'),
+        });
+        this.assignState({ hasQuota: allowed, used: result.used, limit: result.limit });
+    }
+    async reportUsage(_state, ctx) {
+        if (!_state.hasQuota) {
+            await this.documentStore.save(common_1.MarkdownDocument, {
+                markdown: '## Skipped\n\nQuota exhausted — operation not performed.',
+            });
+            return;
+        }
+        await this.quotaClient.report(ctx.userId ?? 'anonymous', ctx.args.quotaType, ctx.args.reportAmount);
+        await this.documentStore.save(common_1.MarkdownDocument, {
+            markdown: [
+                '## Reported',
+                '',
+                `Charged \`${ctx.args.reportAmount}\` units of \`${ctx.args.quotaType}\` to the user's quota.`,
+            ].join('\n'),
+        });
+    }
+};
+exports.QuotaExampleWorkflow = QuotaExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'quota_checked' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], QuotaExampleWorkflow.prototype, "checkQuota", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'quota_checked', to: 'end' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], QuotaExampleWorkflow.prototype, "reportUsage", null);
+exports.QuotaExampleWorkflow = QuotaExampleWorkflow = __decorate([
+    (0, common_1.Workflow)({
+        title: 'Observability - Quota Example',
+        description: 'Demonstrates opt-in quota tracking with @loopstack/quota — check available budget before an operation, then report usage afterward. Backed by Redis when enabled in QuotaModule.forRoot.',
+        schema: QuotaExampleArgsSchema,
+    }),
+    __metadata("design:paramtypes", [quota_1.QuotaClientService])
+], QuotaExampleWorkflow);
+//# sourceMappingURL=quota-example.workflow.js.map

package/dist/workflows/quota/quota-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/quota/quota-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6BAAwB;AACxB,8CAAyF;AAEzF,4CAAsD;AAQtD,MAAM,sBAAsB,GAAG,OAAC,CAAC,MAAM,CAAC;IACtC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC;IACjD,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CACvC,CAAC,CAAC;AAUI,IAAM,oBAAoB,GAA1B,MAAM,oBAAqB,SAAQ,qBAA8B;IACzC;IAA7B,YAA6B,WAA+B;QAC1D,KAAK,EAAE,CAAC;QADmB,gBAAW,GAAX,WAAW,CAAoB;IAE5D,CAAC;IAGK,AAAN,KAAK,CAAC,UAAU,CAAC,MAAyB,EAAE,GAAiC;QAC3E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,IAAI,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAEhG,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC;QACjC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE;gBACR,gBAAgB;gBAChB,EAAE;gBACF,gBAAgB,OAAO,IAAI;gBAC3B,aAAa,MAAM,CAAC,IAAI,IAAI;gBAC5B,cAAc,MAAM,CAAC,KAAK,IAAI;aAC/B,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;QAEH,IAAI,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;IAGK,AAAN,KAAK,CAAC,WAAW,CAAC,MAAyB,EAAE,GAAiC;QAC5E,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;gBAC9C,QAAQ,EAAE,0DAA0D;aACrE,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAEpG,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE;gBACR,aAAa;gBACb,EAAE;gBACF,aAAa,GAAG,CAAC,IAAI,CAAC,YAAY,iBAAiB,GAAG,CAAC,IAAI,CAAC,SAAS,yBAAyB;aAC/F,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AA1CY,oDAAoB;AAMzB;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC;;;;sDAgBnC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;uDAkBhD;+BAzCU,oBAAoB;IANhC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,+BAA+B;QACtC,WAAW,EACT,0LAA0L;QAC5L,MAAM,EAAE,sBAAsB;KAC/B,CAAC;qCAE0C,0BAAkB;GADjD,oBAAoB,CA0ChC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@loopstack/observability-examples",
+  "displayName": "Loopstack Observability Examples",
+  "description": "Workflow examples for observability in Loopstack — opt-in quota tracking and enforcement.",
+  "keywords": [
+    "loopstack",
+    "example",
+    "observability",
+    "quota",
+    "workflow"
+  ],
+  "version": "0.1.0",
+  "license": "MIT",
+  "author": {
+    "name": "Jakob Klippel",
+    "url": "https://www.linkedin.com/in/jakob-klippel/"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./src/*": "./src/*"
+  },
+  "scripts": {
+    "build": "nest build",
+    "compile": "tsc --noEmit",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "watch": "nest build --watch"
+  },
+  "dependencies": {
+    "@loopstack/common": "*",
+    "@loopstack/quota": "*",
+    "@nestjs/common": "^11.1.19",
+    "zod": "^4.3.6"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.6",
+    "@swc/core": "^1.15.33",
+    "unplugin-swc": "^1.5.9"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './observability-examples.module';
+export * from './workflows/quota/quota-example.workflow';

package/src/observability-examples.module.ts

@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+import { StudioApp } from '@loopstack/common';
+import { QuotaModule } from '@loopstack/quota';
+import { QuotaExampleWorkflow } from './workflows/quota/quota-example.workflow';
+
+@StudioApp({
+  title: 'Observability Examples',
+  workflows: [QuotaExampleWorkflow],
+})
+@Module({
+  imports: [QuotaModule.forRoot({ enabled: false })],
+  providers: [QuotaExampleWorkflow],
+  exports: [QuotaExampleWorkflow],
+})
+export class ObservabilityExamplesModule {}

package/src/workflows/quota/quota-example.workflow.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { BaseWorkflow, MarkdownDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { QuotaClientService } from '@loopstack/quota';
+
+interface QuotaExampleState {
+  hasQuota?: boolean;
+  used?: number;
+  limit?: number;
+}
+
+const QuotaExampleArgsSchema = z.object({
+  quotaType: z.string().default('ai_generate_text'),
+  reportAmount: z.number().default(1000),
+});
+
+type QuotaExampleArgs = z.infer<typeof QuotaExampleArgsSchema>;
+
+@Workflow({
+  title: 'Observability - Quota Example',
+  description:
+    'Demonstrates opt-in quota tracking with @loopstack/quota — check available budget before an operation, then report usage afterward. Backed by Redis when enabled in QuotaModule.forRoot.',
+  schema: QuotaExampleArgsSchema,
+})
+export class QuotaExampleWorkflow extends BaseWorkflow<QuotaExampleArgs> {
+  constructor(private readonly quotaClient: QuotaClientService) {
+    super();
+  }
+
+  @Transition({ to: 'quota_checked' })
+  async checkQuota(_state: QuotaExampleState, ctx: RunContext<QuotaExampleArgs>) {
+    const result = await this.quotaClient.checkQuota(ctx.userId ?? 'anonymous', ctx.args.quotaType);
+
+    const allowed = !result.exceeded;
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: [
+        '## Quota Check',
+        '',
+        `- Allowed: \`${allowed}\``,
+        `- Used: \`${result.used}\``,
+        `- Limit: \`${result.limit}\``,
+      ].join('\n'),
+    });
+
+    this.assignState({ hasQuota: allowed, used: result.used, limit: result.limit });
+  }
+
+  @Transition({ from: 'quota_checked', to: 'end' })
+  async reportUsage(_state: QuotaExampleState, ctx: RunContext<QuotaExampleArgs>) {
+    if (!_state.hasQuota) {
+      await this.documentStore.save(MarkdownDocument, {
+        markdown: '## Skipped\n\nQuota exhausted — operation not performed.',
+      });
+      return;
+    }
+
+    await this.quotaClient.report(ctx.userId ?? 'anonymous', ctx.args.quotaType, ctx.args.reportAmount);
+
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: [
+        '## Reported',
+        '',
+        `Charged \`${ctx.args.reportAmount}\` units of \`${ctx.args.quotaType}\` to the user's quota.`,
+      ].join('\n'),
+    });
+  }
+}