@flowrunner/cli 0.1.8 → 0.1.9-dev.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/README.md +8 -8
  2. package/ai-docs/instructions/service-code-format/01-service-structure.md +4 -3
  3. package/ai-docs/instructions/service-code-format/02-zod-types.md +8 -0
  4. package/ai-docs/instructions/service-code-format/03-parameters.md +166 -10
  5. package/ai-docs/instructions/service-code-format/04-http-requests.md +19 -15
  6. package/ai-docs/instructions/service-code-format/05-dictionaries.md +14 -0
  7. package/ai-docs/instructions/service-code-format/06-oauth2.md +1 -5
  8. package/ai-docs/instructions/service-code-format/07-actions.md +18 -13
  9. package/ai-docs/instructions/service-code-format/11-output-model.md +42 -6
  10. package/ai-docs/instructions/service-code-format/12-service-readme.md +1 -1
  11. package/ai-docs/instructions/service-code-format/14-reference-service.md +5 -4
  12. package/ai-docs/instructions/service-code-format/15-unit-tests.md +2 -1
  13. package/ai-docs/instructions/service-code-format/16-gotchas.md +31 -1
  14. package/ai-docs/instructions/service-code-format/17-client-certificates.md +5 -3
  15. package/ai-docs/instructions/service-code-format/README.md +1 -1
  16. package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +1 -1
  17. package/dist/cli.js +285 -42
  18. package/dist/cli.js.map +3 -3
  19. package/dist/index.js +284 -41
  20. package/dist/index.js.map +3 -3
  21. package/dist/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
  22. package/dist/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
  23. package/dist/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
  24. package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
  25. package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
  26. package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
  27. package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
  28. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
  29. package/dist/types/flow-extension-runner/src/v2/types.d.ts +21 -9
  30. package/dist/types/shared/src/constants/activity-log.d.ts +1496 -0
  31. package/dist/types/shared/src/constants/docs.d.ts +2 -0
  32. package/dist/types/shared/src/constants/notification-types.d.ts +11 -5
  33. package/dist/types/shared/src/scheme/activity-log-base.d.ts +35 -0
  34. package/dist/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
  35. package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
  36. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
  37. package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
  38. package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
  39. package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
  40. package/dist/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
  41. package/dist/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
  42. package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
  43. package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
  44. package/package.json +1 -1
  45. package/runtime/index.js +267 -41
  46. package/runtime/index.js.map +3 -3
  47. package/runtime/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
  48. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
  49. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
  50. package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
  51. package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
  52. package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
  53. package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
  54. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
  55. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +21 -9
  56. package/runtime/types/shared/src/constants/activity-log.d.ts +1496 -0
  57. package/runtime/types/shared/src/constants/docs.d.ts +2 -0
  58. package/runtime/types/shared/src/constants/notification-types.d.ts +11 -5
  59. package/runtime/types/shared/src/scheme/activity-log-base.d.ts +35 -0
  60. package/runtime/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
  61. package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
  62. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
  63. package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
  64. package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
  65. package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
  66. package/runtime/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
  67. package/runtime/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
  68. package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
  69. package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
  70. package/templates/blank/files/src/index.js +1 -1
  71. package/templates/demo-todo-list/files/src/index.js +7 -7
  72. package/templates/qa-test/files/README.md +23 -8
  73. package/templates/qa-test/files/src/index.js +367 -38
@@ -82,7 +82,7 @@ const ext = Flowrunner.createExtension({
82
82
  logger.debug(`[${ method.toUpperCase() }] ${ url } (harness ${ context.harnessVersion })`)
83
83
 
84
84
  try {
85
- return await Flowrunner.Request[method.toLowerCase()](url)
85
+ return await new Flowrunner.Request(url, method)
86
86
  .set(headers)
87
87
  .query(query)
88
88
  .send(body)
@@ -417,48 +417,377 @@ ext.addAction({
417
417
  })
418
418
 
419
419
  ext.addAction({
420
- category : '2. Params',
421
- id : 'paramsGeneratedAtRuntime',
422
- label : 'Params — Generated At Runtime',
423
- description : 'Picking a parent generates one extra field per child. Change the parent and watch them change.',
420
+ category : '2. Params',
421
+ id : 'paramsUnknownStripped',
422
+ label : 'Params — Unknown Fields Are Stripped',
423
+ description: 'Declares one param. Anything else the flow sends should NOT come back.',
424
+ params : z.object({
425
+ keep: z.string().optional().label('Keep'),
426
+ }),
427
+ result : { params: {} },
428
+ execute : ({ params }) => ({ params, keys: Object.keys(params) }),
429
+ })
430
+
431
+ // ─── 3. Dynamic Fields ───────────────────────────────────────────────────────
432
+ // Fields loaded at design time from the values of other params. `.dynamicProps()` loads the fields INSIDE one
433
+ // param (a loose object, or a list of them); `dynamicParams` loads extra top-level params of the action. Both
434
+ // load again when a param in `dependsOn` changes, and keep what was entered for fields that come back.
435
+
436
+ const RECORD_TYPES = [
437
+ { id: 'contact', name: 'Contact' },
438
+ { id: 'product', name: 'Product' },
439
+ { id: 'event', name: 'Event' },
440
+ ]
441
+
442
+ const getRecordTypesDictionary = ext.dictionary({
443
+ id : 'getRecordTypesDictionary',
444
+ label : 'Record Types',
445
+ description: 'Three record types, each with its own fields. All three have "Name", so it survives a switch.',
446
+ execute : ({ search }) => RECORD_TYPES
447
+ .filter(type => matches(type.name, search))
448
+ .map(type => ({ label: type.name, value: type.id })),
449
+ })
450
+
451
+ // The fields of one record type — every kind of field a loader can return. Built per call: a loader answers
452
+ // with fresh zod each time.
453
+ const recordFields = recordType => {
454
+ switch (recordType) {
455
+ case 'contact':
456
+ return {
457
+ name : z.string().label('Name'),
458
+ email: z.email().optional().label('Email (format-checked)'),
459
+ age : z.number().int().min(0).max(150).optional().label('Age (0–150)'),
460
+ vip : z.boolean().optional().default(false).label('VIP (defaults to false)'),
461
+ tier : z.enum(['free', 'pro', 'enterprise'])
462
+ .labels({ free: 'Free', pro: 'Pro', enterprise: 'Enterprise' })
463
+ .optional()
464
+ .label('Tier (labelled enum)'),
465
+ notes: z.text().optional().label('Notes (multi-line)'),
466
+ }
467
+
468
+ case 'product':
469
+ return {
470
+ name : z.string().label('Name'),
471
+ price : z.number().min(0).label('Price (≥ 0)'),
472
+ inStock : z.boolean().label('In Stock'),
473
+ tags : z.array(z.string()).optional().label('Tags (list of text)'),
474
+ category: z.enum(['books', 'games', 'music']).default('books').label('Category (defaults to books)'),
475
+ }
476
+
477
+ case 'event':
478
+ return {
479
+ name : z.string().label('Name'),
480
+ startsAt: z.coerce.date().label('Starts At (date)'),
481
+ link : z.url().optional().label('Link (format-checked)'),
482
+ venue : z.object({
483
+ city: z.string().label('City'),
484
+ room: z.string().optional().label('Room'),
485
+ }).optional().label('Venue (nested object)'),
486
+ }
487
+
488
+ default:
489
+ return {}
490
+ }
491
+ }
492
+
493
+ ext.addAction({
494
+ category : '3. Dynamic Fields',
495
+ id : 'dynamicPropsEveryType',
496
+ label : 'Dynamic Props — Every Field Type',
497
+ description: 'Pick a record type: "Record" loads its fields — text, email, number, boolean, enum, date, list, nested object.',
498
+ params : z.object({
499
+ recordType: z.string().label('Record Type').dictionary(getRecordTypesDictionary),
500
+ record : z.looseObject({}).label('Record').dynamicProps({
501
+ dependsOn: ['recordType'],
502
+ execute : ({ criteria }) => recordFields(criteria.recordType),
503
+ }),
504
+ }),
505
+ result : { params: {} },
506
+ // The loaded fields arrive nested under `record`, as their declared types
507
+ execute : ({ params }) => ({ params, types: typesOf(params.record) }),
508
+ })
509
+
510
+ ext.addAction({
511
+ category : '3. Dynamic Fields',
512
+ id : 'dynamicPropsDeclaredKeys',
513
+ label : 'Dynamic Props — Declared Keys Plus Loaded Ones',
514
+ description: 'Picking a parent loads one field per child INSIDE "Child Fields", after its declared "Comment".',
515
+ params : z.object({
516
+ parentId : z.string().label('Parent').dictionary(getParentsDictionary),
517
+ // A loose object, so the loaded keys are kept. Declared keys (`comment`) are shown first, loaded ones after.
518
+ childFields: z.looseObject({ comment: z.string().optional().label('Comment') })
519
+ .optional()
520
+ .label('Child Fields')
521
+ .dynamicProps({
522
+ dependsOn: ['parentId'],
523
+ execute : ({ criteria }) => {
524
+ const shape = {}
525
+
526
+ for (const child of CHILDREN[criteria.parentId] || []) {
527
+ shape[`field_${ child.id }`] = z.string().optional().label(`Field for ${ child.name }`)
528
+ }
529
+
530
+ return shape
531
+ },
532
+ }),
533
+ }),
534
+ result : { params: {} },
535
+ execute : ({ params }) => ({ params, keys: Object.keys(params.childFields || {}) }),
536
+ })
537
+
538
+ ext.addAction({
539
+ category : '3. Dynamic Fields',
540
+ id : 'dynamicPropsWithDictionaries',
541
+ label : 'Dynamic Props — Dropdowns Inside',
542
+ description: 'The loaded fields are dropdowns: plain, dependent (child of the loaded parent), paged and failing.',
543
+ params : z.object({
544
+ withChild: z.boolean().optional().default(true).label('Include the dependent "Child" dropdown'),
545
+ lookups : z.looseObject({}).label('Lookups').dynamicProps({
546
+ dependsOn: ['withChild'],
547
+ // `criteria.withChild` arrives as a boolean, whatever form the flow sent it in
548
+ execute : ({ criteria }) => ({
549
+ parentId : z.string().label('Parent').dictionary(getParentsDictionary),
550
+ ...(criteria.withChild ? { childId: z.string().optional().label('Child (depends on Parent)').dictionary(getChildrenDictionary) } : {}),
551
+ pagedId : z.string().optional().label('Paged (137 items)').dictionary(getPagedDictionary),
552
+ failingId: z.string().optional().label('Failing').dictionary(getFailingDictionary),
553
+ }),
554
+ }),
555
+ }),
556
+ result : { params: {} },
557
+ execute : ({ params }) => ({ params }),
558
+ })
559
+
560
+ ext.addAction({
561
+ category : '3. Dynamic Fields',
562
+ id : 'dynamicPropsListOfObjects',
563
+ label : 'Dynamic Props — List Of Objects',
564
+ description: 'Each row of "Rows" gets the fields of the picked record type. `.dynamicProps()` sits on the list.',
565
+ params : z.object({
566
+ recordType: z.string().label('Record Type').dictionary(getRecordTypesDictionary),
567
+ rows : z.array(z.looseObject({})).optional().label('Rows').dynamicProps({
568
+ dependsOn: ['recordType'],
569
+ execute : ({ criteria }) => recordFields(criteria.recordType),
570
+ }),
571
+ }),
572
+ result : { params: {} },
573
+ execute : ({ params }) => ({ params, rows: (params.rows || []).length }),
574
+ })
575
+
576
+ ext.addAction({
577
+ category : '3. Dynamic Fields',
578
+ id : 'dynamicPropsNoDependencies',
579
+ label : 'Dynamic Props — No Dependencies',
580
+ description: 'No `dependsOn`: the fields load once when the block opens, and again only on a connection change.',
581
+ params : z.object({
582
+ custom: z.looseObject({}).label('Account Custom Fields').dynamicProps({
583
+ execute: () => ({
584
+ costCenter: z.string().optional().label('Cost Center'),
585
+ priority : z.enum(['low', 'normal', 'high']).optional().label('Priority'),
586
+ loadedAt : z.string().optional().default(new Date().toISOString()).label('Loaded At (default = when it loaded)'),
587
+ }),
588
+ }),
589
+ }),
590
+ result : { params: {} },
591
+ execute : ({ params }) => ({ params }),
592
+ })
593
+
594
+ ext.addAction({
595
+ category : '3. Dynamic Fields',
596
+ id : 'dynamicPropsCriteriaTypes',
597
+ label : 'Dynamic Props — Several Dependencies, Typed',
598
+ description: 'Three dependencies of different types. Each loaded label shows the type its criteria value arrived as.',
599
+ params : z.object({
600
+ count : z.number().int().min(0).max(10).default(2).label('How many fields (0–10)'),
601
+ withFlags: z.boolean().optional().default(false).label('Add a toggle per field'),
602
+ prefix : z.string().optional().default('field').label('Field name prefix'),
603
+ generated: z.looseObject({}).label('Generated').dynamicProps({
604
+ dependsOn: ['count', 'withFlags', 'prefix'],
605
+ // Only the params named in `dependsOn` arrive, coerced by their own schemas
606
+ execute : ({ criteria }) => {
607
+ const { count, withFlags, prefix } = criteria
608
+ const types = `count: ${ typeof count }, withFlags: ${ typeof withFlags }`
609
+ const shape = {}
610
+
611
+ for (let index = 1; index <= count; index++) {
612
+ shape[`${ prefix }_${ index }`] = z.string().optional().label(`${ prefix } ${ index } (${ types })`)
613
+
614
+ if (withFlags) {
615
+ shape[`${ prefix }_${ index }_on`] = z.boolean().optional().label(`${ prefix } ${ index } enabled`)
616
+ }
617
+ }
618
+
619
+ return shape
620
+ },
621
+ }),
622
+ }),
623
+ result : { params: {} },
624
+ execute : ({ params }) => ({ params }),
625
+ })
626
+
627
+ // One def, two params: the runner generates a loader per use, so each param loads on its own.
628
+ const addressFields = {
629
+ dependsOn: ['country'],
630
+ execute : ({ criteria }) => criteria.country === 'US'
631
+ ? {
632
+ street: z.string().label('Street'),
633
+ state : z.enum(['CA', 'NY', 'TX']).label('State'),
634
+ zip : z.string().regex(/^\d{5}$/, 'Five digits').label('ZIP (5 digits)'),
635
+ }
636
+ : {
637
+ street : z.string().label('Street'),
638
+ county : z.string().optional().label('County'),
639
+ postcode: z.string().label('Postcode'),
640
+ },
641
+ }
642
+
643
+ ext.addAction({
644
+ category : '3. Dynamic Fields',
645
+ id : 'dynamicPropsSharedDefinition',
646
+ label : 'Dynamic Props — One Definition, Two Params',
647
+ description: 'Billing and Shipping share one definition. Switch the country: both reload; "Street" keeps its value.',
648
+ params : z.object({
649
+ country : z.enum(['US', 'UK']).labels({ US: 'United States', UK: 'United Kingdom' }).default('US').label('Country'),
650
+ billing : z.looseObject({}).label('Billing Address').dynamicProps(addressFields),
651
+ shipping: z.looseObject({}).optional().label('Shipping Address').dynamicProps(addressFields),
652
+ }),
653
+ result : { params: {} },
654
+ execute : ({ params }) => ({ params }),
655
+ })
656
+
657
+ ext.addAction({
658
+ category : '3. Dynamic Fields',
659
+ id : 'dynamicPropsLoaderStates',
660
+ label : 'Dynamic Props — Loader States',
661
+ description: 'Pick how the loader behaves: slow, failing, invalid, empty, or repeating a declared key.',
662
+ params : z.object({
663
+ behaviour : z.enum(['ok', 'slow', 'fail', 'invalid', 'empty', 'repeatsDeclared'])
664
+ .labels({
665
+ ok : 'Loads two fields',
666
+ slow : 'Takes 3 seconds',
667
+ fail : 'Throws',
668
+ invalid : 'Returns something that is not a schema',
669
+ empty : 'Returns no fields',
670
+ repeatsDeclared: 'Returns a field the param already declares',
671
+ })
672
+ .default('ok')
673
+ .label('Loader Behaviour'),
674
+ loadedInto: z.looseObject({ declared: z.string().optional().label('Declared Field') })
675
+ .optional()
676
+ .label('Loaded Into')
677
+ .dynamicProps({
678
+ dependsOn: ['behaviour'],
679
+ execute : async ({ criteria }) => {
680
+ const loaded = { first: z.string().optional().label('First'), second: z.number().optional().label('Second') }
681
+
682
+ switch (criteria.behaviour) {
683
+ case 'slow':
684
+ await new Promise(resolve => setTimeout(resolve, 3000))
685
+
686
+ return loaded
687
+
688
+ case 'fail':
689
+ throw new Error('QA: this loader fails on purpose')
690
+
691
+ case 'invalid':
692
+ return 'not a schema'
693
+
694
+ case 'empty':
695
+ return {}
696
+
697
+ case 'repeatsDeclared':
698
+ return { declared: z.string() }
699
+
700
+ default:
701
+ return loaded
702
+ }
703
+ },
704
+ }),
705
+ }),
706
+ result : { params: {} },
707
+ execute : ({ params }) => ({ params }),
708
+ })
709
+
710
+ ext.addAction({
711
+ category : '3. Dynamic Fields',
712
+ id : 'dynamicParamsPerChild',
713
+ label : 'Dynamic Params — One Field Per Child',
714
+ description : 'Picking a parent adds one top-level field per child. Change the parent and watch them change.',
424
715
  params : z.object({
425
716
  parentId: z.string().label('Parent').dictionary(getParentsDictionary),
426
717
  }),
427
718
  dynamicParams: {
428
- criteria: z.object({ parentId: z.string().optional() }),
429
- resolve : ({ criteria }) => {
719
+ dependsOn: ['parentId'],
720
+ execute : ({ criteria }) => {
430
721
  const shape = {}
431
722
 
432
723
  for (const child of CHILDREN[criteria.parentId] || []) {
433
724
  shape[`field_${ child.id }`] = z.string().optional().label(`Field for ${ child.name }`)
434
725
  }
435
726
 
436
- return z.object(shape)
727
+ return shape
437
728
  },
438
729
  },
439
730
  result : { params: {} },
440
- // Generated fields ride through because the action declares dynamicParams — compare with the next one.
731
+ // Loaded fields ride through because the action declares dynamicParams — compare with "Unknown Fields Are
732
+ // Stripped" in 2. Params.
441
733
  execute : ({ params }) => ({ params, keys: Object.keys(params) }),
442
734
  })
443
735
 
444
736
  ext.addAction({
445
- category : '2. Params',
446
- id : 'paramsUnknownStripped',
447
- label : 'Params — Unknown Fields Are Stripped',
448
- description: 'Declares one param. Anything else the flow sends should NOT come back.',
449
- params : z.object({
450
- keep: z.string().optional().label('Keep'),
737
+ category : '3. Dynamic Fields',
738
+ id : 'dynamicParamsEveryType',
739
+ label : 'Dynamic Params — Every Field Type',
740
+ description : 'Pick a record type: its fields are added as top-level params, dropdowns and nested object included.',
741
+ params : z.object({
742
+ recordType: z.string().label('Record Type').dictionary(getRecordTypesDictionary),
451
743
  }),
452
- result : { params: {} },
453
- execute : ({ params }) => ({ params, keys: Object.keys(params) }),
744
+ dynamicParams: {
745
+ dependsOn: ['recordType'],
746
+ execute : ({ criteria }) => ({
747
+ ...recordFields(criteria.recordType),
748
+ owner: z.string().optional().label('Owner (dropdown)').dictionary(getPagedDictionary),
749
+ }),
750
+ },
751
+ result : { params: {} },
752
+ execute : ({ params }) => ({ params, types: typesOf(params) }),
753
+ })
754
+
755
+ ext.addAction({
756
+ category : '3. Dynamic Fields',
757
+ id : 'dynamicParamsAndProps',
758
+ label : 'Dynamic Params And Props Together',
759
+ description : 'The record type adds top-level params; the parent loads fields into "Child Fields". Both at once.',
760
+ params : z.object({
761
+ recordType : z.string().label('Record Type').dictionary(getRecordTypesDictionary),
762
+ parentId : z.string().optional().label('Parent').dictionary(getParentsDictionary),
763
+ childFields: z.looseObject({}).optional().label('Child Fields').dynamicProps({
764
+ dependsOn: ['parentId'],
765
+ execute : ({ criteria }) => Object.fromEntries((CHILDREN[criteria.parentId] || [])
766
+ .map(child => [`field_${ child.id }`, z.string().optional().label(`Field for ${ child.name }`)])),
767
+ }),
768
+ }),
769
+ dynamicParams: {
770
+ dependsOn: ['recordType'],
771
+ execute : ({ criteria }) => recordFields(criteria.recordType),
772
+ },
773
+ result : { params: {} },
774
+ execute : ({ params }) => ({ params }),
454
775
  })
455
776
 
456
- // ─── 3. Results ──────────────────────────────────────────────────────────────
777
+ // The JS type each value of an object arrived as — a Date is reported as one, not as "object".
778
+ function typesOf(values = {}) {
779
+ return Object.fromEntries(Object.entries(values).map(([key, value]) => [
780
+ key,
781
+ value instanceof Date ? 'Date' : Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value,
782
+ ]))
783
+ }
784
+
785
+ // ─── 4. Results ──────────────────────────────────────────────────────────────
457
786
  // One action per `result` FORM, because each publishes a different return type or sample source — that is
458
787
  // what downstream blocks bind their fields to.
459
788
 
460
789
  ext.addAction({
461
- category : '3. Results',
790
+ category : '4. Results',
462
791
  id : 'returnsObject',
463
792
  label : 'Returns — Object',
464
793
  description: 'Literal object sample. Published return type: OBJECT.',
@@ -467,7 +796,7 @@ ext.addAction({
467
796
  })
468
797
 
469
798
  ext.addAction({
470
- category : '3. Results',
799
+ category : '4. Results',
471
800
  id : 'returnsList',
472
801
  label : 'Returns — List',
473
802
  description: 'Literal list sample. Set the size to check large payloads. Published return type: LIST.',
@@ -479,7 +808,7 @@ ext.addAction({
479
808
  })
480
809
 
481
810
  ext.addAction({
482
- category : '3. Results',
811
+ category : '4. Results',
483
812
  id : 'returnsNothing',
484
813
  label : 'Returns — Nothing',
485
814
  description: 'No `result` declared and nothing returned. Published return type: VOID.',
@@ -487,7 +816,7 @@ ext.addAction({
487
816
  })
488
817
 
489
818
  ext.addAction({
490
- category : '3. Results',
819
+ category : '4. Results',
491
820
  id : 'returnsSampleFromSchema',
492
821
  label : 'Returns — Sample From A Schema',
493
822
  description: 'The sample comes from .example() on the result schema rather than a literal.',
@@ -499,7 +828,7 @@ ext.addAction({
499
828
  })
500
829
 
501
830
  ext.addAction({
502
- category : '3. Results',
831
+ category : '4. Results',
503
832
  id : 'returnsSampleFromLoader',
504
833
  label : 'Returns — Sample Computed From Params',
505
834
  description: 'The sample is computed from the params — toggle "Detailed" and watch the shape change.',
@@ -512,10 +841,10 @@ ext.addAction({
512
841
  execute : ({ params }) => (params.detailed ? { id: 'x', detail: { extra: true, nested: [1, 2, 3] } } : { id: 'x' }),
513
842
  })
514
843
 
515
- // ─── 4. Runtime ──────────────────────────────────────────────────────────────
844
+ // ─── 5. Runtime ──────────────────────────────────────────────────────────────
516
845
 
517
846
  ext.addAction({
518
- category : '4. Runtime',
847
+ category : '5. Runtime',
519
848
  id : 'callHelpers',
520
849
  label : 'Call Helpers',
521
850
  description: 'Invokes each helper declared on the extension and returns what came back.',
@@ -530,7 +859,7 @@ ext.addAction({
530
859
  })
531
860
 
532
861
  ext.addAction({
533
- category : '4. Runtime',
862
+ category : '5. Runtime',
534
863
  id : 'emitLogs',
535
864
  label : 'Emit Logs',
536
865
  description: 'Writes one line at each level. Check they reach the runtime logs.',
@@ -549,7 +878,7 @@ ext.addAction({
549
878
  })
550
879
 
551
880
  ext.addAction({
552
- category : '4. Runtime',
881
+ category : '5. Runtime',
553
882
  id : 'throwError',
554
883
  label : 'Throw An Error',
555
884
  description: 'Fails on purpose. Check the message reaches the console and the flow.',
@@ -563,7 +892,7 @@ ext.addAction({
563
892
  })
564
893
 
565
894
  ext.addAction({
566
- category : '4. Runtime',
895
+ category : '5. Runtime',
567
896
  id : 'runLongerThanATimeout',
568
897
  label : 'Run Longer Than A Timeout',
569
898
  description: 'Sleeps, then returns. Platform policy is no timeout on service code — verify a long run survives.',
@@ -580,7 +909,7 @@ ext.addAction({
580
909
  })
581
910
 
582
911
  ext.addAction({
583
- category : '4. Runtime',
912
+ category : '5. Runtime',
584
913
  id : 'readOauthWithoutDeclaringIt',
585
914
  label : 'Read OAuth Without Declaring It',
586
915
  description: 'This service declares no OAuth, so reading ctx.oauth should fail loudly rather than return null.',
@@ -588,10 +917,10 @@ ext.addAction({
588
917
  execute : ({ oauth }) => ({ accessToken: oauth.accessToken }),
589
918
  })
590
919
 
591
- // ─── 5. HTTP ─────────────────────────────────────────────────────────────────
920
+ // ─── 6. HTTP ─────────────────────────────────────────────────────────────────
592
921
 
593
922
  ext.addAction({
594
- category : '5. HTTP',
923
+ category : '6. HTTP',
595
924
  id : 'callHttpEndpoint',
596
925
  label : 'Call An HTTP Endpoint',
597
926
  description: 'Runs the shared apiRequest helper against a URL you supply. Try https://httpbin.org/get.',
@@ -630,12 +959,12 @@ ext.addAction({
630
959
  },
631
960
  })
632
961
 
633
- // ─── 6. Files ────────────────────────────────────────────────────────────────
962
+ // ─── 7. Files ────────────────────────────────────────────────────────────────
634
963
 
635
964
  const SCOPES = ['FLOW', 'EXECUTION', 'WORKSPACE']
636
965
 
637
966
  ext.addAction({
638
- category : '6. Files',
967
+ category : '7. Files',
639
968
  id : 'filesRoundTrip',
640
969
  label : 'Files — Upload, Read, List, Delete',
641
970
  description: 'The whole FilesApi surface in one call. The quickest end-to-end check of file storage.',
@@ -664,7 +993,7 @@ ext.addAction({
664
993
  })
665
994
 
666
995
  ext.addAction({
667
- category : '6. Files',
996
+ category : '7. Files',
668
997
  id : 'filesUsage',
669
998
  label : 'Files — Storage Usage',
670
999
  description: 'Workspace storage usage and quota. Run it either side of a round trip.',
@@ -672,7 +1001,7 @@ ext.addAction({
672
1001
  execute : ({ files }) => files.usage(),
673
1002
  })
674
1003
 
675
- // ─── 7. Polling triggers ─────────────────────────────────────────────────────
1004
+ // ─── 8. Polling triggers ─────────────────────────────────────────────────────
676
1005
  // All three mechanisms, fed by a synthetic source so they fire without a real API. `emitPerPoll` controls
677
1006
  // how many brand-new items each poll invents — set it to 0 to prove a quiet poll emits nothing.
678
1007
 
@@ -706,7 +1035,7 @@ const emitPerPoll = () => z.object({
706
1035
  })
707
1036
 
708
1037
  ext.addPollingTrigger({
709
- category : '7. Triggers',
1038
+ category : '8. Triggers',
710
1039
  id : 'onNewItemByDedupe',
711
1040
  label : 'On New Item — by id (dedupe)',
712
1041
  description: 'Emits ids it has not seen before. Polling interval can be customized (minimum 30 seconds).',
@@ -717,7 +1046,7 @@ ext.addPollingTrigger({
717
1046
  })
718
1047
 
719
1048
  ext.addPollingTrigger({
720
- category : '7. Triggers',
1049
+ category : '8. Triggers',
721
1050
  id : 'onNewItemByWatermark',
722
1051
  label : 'On New Item — by timestamp (watermark)',
723
1052
  description: 'Emits items newer than the stored marker. Polling interval can be customized (minimum 30 seconds).',
@@ -728,7 +1057,7 @@ ext.addPollingTrigger({
728
1057
  })
729
1058
 
730
1059
  ext.addPollingTrigger({
731
- category : '7. Triggers',
1060
+ category : '8. Triggers',
732
1061
  id : 'onNewItemByOwnState',
733
1062
  label : 'On New Item — managing its own state (poll)',
734
1063
  description: 'Owns its own state and returns it, so you can watch it advance. '