zinkee 0.1.61 → 0.1.63

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.
@@ -2,7 +2,7 @@ import {
2
2
  buildJsonSuccess,
3
3
  getSchemaFieldTypeDefinitions,
4
4
  resolveSchemaFieldType
5
- } from "./chunk-W3BI6KES.js";
5
+ } from "./chunk-UAL4VMAW.js";
6
6
 
7
7
  // src/utils/examples.ts
8
8
  var SAMPLE_UUID = "550e8400-e29b-41d4-a716-446655440001";
@@ -805,6 +805,169 @@ var specificExamples = {
805
805
  "where": [
806
806
  { "field": "contact-email", "op": "is_not_empty" }
807
807
  ]
808
+ }`
809
+ }
810
+ ],
811
+ "records aggregate": [
812
+ {
813
+ description: "Sum amount and count deals per close-date month (buckets: day, week, month, quarter, year). Deals without close-date form one group with value/label null, listed last; meta.aggregate tells whether groups were cut by the limit.",
814
+ command: "zinkee --json records aggregate deals --group-by close-date:month --metric total=sum:amount --metric n=count",
815
+ raw: `{
816
+ "groupBy": [
817
+ { "field": "close-date", "bucket": "month" }
818
+ ],
819
+ "metrics": [
820
+ { "op": "sum", "field": "amount", "as": "total" },
821
+ { "op": "count", "as": "n" }
822
+ ]
823
+ }`,
824
+ response: `[
825
+ {
826
+ "key": {
827
+ "close-date": { "value": "2026-08-01", "label": "2026-08" }
828
+ },
829
+ "metrics": { "total": 18400, "n": 5 }
830
+ },
831
+ {
832
+ "key": {
833
+ "close-date": { "value": "2026-09-01", "label": "2026-09" }
834
+ },
835
+ "metrics": { "total": 26150.75, "n": 8 }
836
+ },
837
+ {
838
+ "key": {
839
+ "close-date": { "value": "2026-10-01", "label": "2026-10" }
840
+ },
841
+ "metrics": { "total": 63550.75, "n": 21 }
842
+ },
843
+ {
844
+ "key": {
845
+ "close-date": { "value": null, "label": null }
846
+ },
847
+ "metrics": { "total": 3200, "n": 2 }
848
+ }
849
+ ]`,
850
+ responseMeta: {
851
+ aggregate: { count: 4, total: 4, limit: 100, truncated: false, timezone: "Europe/Madrid" }
852
+ }
853
+ },
854
+ {
855
+ description: "Top 3 stage/month pairs by total: group by an option field and a month bucket, sort by a metric alias and limit the groups. Option keys return the option id as value and its name as label.",
856
+ command: "zinkee --json records aggregate deals --group-by stage --group-by close-date:month --metric n=count --metric total=sum:amount --sort total:desc --limit 3 --timezone Europe/Madrid",
857
+ raw: `{
858
+ "groupBy": [
859
+ { "field": "stage" },
860
+ { "field": "close-date", "bucket": "month" }
861
+ ],
862
+ "metrics": [
863
+ { "op": "count", "as": "n" },
864
+ { "op": "sum", "field": "amount", "as": "total" }
865
+ ],
866
+ "sort": [
867
+ { "by": "total", "direction": "DESC" }
868
+ ],
869
+ "limit": 3,
870
+ "timezone": "Europe/Madrid"
871
+ }`,
872
+ response: `[
873
+ {
874
+ "key": {
875
+ "stage": { "value": 2, "label": "Negociaci\xF3n" },
876
+ "close-date": { "value": "2026-10-01", "label": "2026-10" }
877
+ },
878
+ "metrics": { "n": 12, "total": 48250.5 }
879
+ },
880
+ {
881
+ "key": {
882
+ "stage": { "value": 3, "label": "Ganado" },
883
+ "close-date": { "value": "2026-09-01", "label": "2026-09" }
884
+ },
885
+ "metrics": { "n": 6, "total": 21900 }
886
+ },
887
+ {
888
+ "key": {
889
+ "stage": { "value": 1, "label": "Propuesta" },
890
+ "close-date": { "value": "2026-10-01", "label": "2026-10" }
891
+ },
892
+ "metrics": { "n": 9, "total": 15300.25 }
893
+ }
894
+ ]`,
895
+ responseMeta: {
896
+ aggregate: { count: 3, total: 7, limit: 3, truncated: true, timezone: "Europe/Madrid" }
897
+ }
898
+ },
899
+ {
900
+ description: "Totals without --group-by: one group with an empty key. Default aliases are count and <op>_<field>; avg/min/max are null when no record has a value, and min/max on a date return a UTC instant.",
901
+ command: 'zinkee --json records aggregate deals --where "status eq OPEN" --metric count --metric total=sum:amount --metric avg:amount --metric max:close-date',
902
+ raw: `{
903
+ "where": [
904
+ { "field": "status", "op": "eq", "value": "OPEN" }
905
+ ],
906
+ "metrics": [
907
+ { "op": "count" },
908
+ { "op": "sum", "field": "amount", "as": "total" },
909
+ { "op": "avg", "field": "amount" },
910
+ { "op": "max", "field": "close-date" }
911
+ ]
912
+ }`,
913
+ response: `[
914
+ {
915
+ "key": {},
916
+ "metrics": {
917
+ "count": 25,
918
+ "total": 96001.25,
919
+ "avg_amount": 3840.05,
920
+ "max_close-date": "2026-10-30T23:00:00Z"
921
+ }
922
+ }
923
+ ]`,
924
+ responseMeta: {
925
+ aggregate: { count: 1, total: 1, limit: 100, truncated: false, timezone: "Europe/Madrid" }
926
+ }
927
+ },
928
+ {
929
+ description: "Filter with an OR tree (--where-json) and a search term, then rank contacts by total amount. --where/--where-json/--search behave exactly as in records query.",
930
+ command: `zinkee --json records aggregate deals --where-json '{"or":[{"field":"stage","op":"in","value":[2,3]},{"field":"amount","op":"gt","value":10000}]}' --search garcia --group-by contact-name --metric total=sum:amount --metric deals=count --sort total:desc --limit 10`,
931
+ raw: `{
932
+ "where": {
933
+ "or": [
934
+ { "field": "stage", "op": "in", "value": [2, 3] },
935
+ { "field": "amount", "op": "gt", "value": 10000 }
936
+ ]
937
+ },
938
+ "search": { "term": "garcia" },
939
+ "groupBy": [
940
+ { "field": "contact-name" }
941
+ ],
942
+ "metrics": [
943
+ { "op": "sum", "field": "amount", "as": "total" },
944
+ { "op": "count", "as": "deals" }
945
+ ],
946
+ "sort": [
947
+ { "by": "total", "direction": "DESC" }
948
+ ],
949
+ "limit": 10
950
+ }`
951
+ },
952
+ {
953
+ description: "Native payload with --raw: distinct customers and amount range per quarter, newest quarter first. Flags such as --metric or --limit replace the same key of the raw payload.",
954
+ command: `zinkee --json records aggregate deals --raw '{"where":[{"field":"status","op":"neq","value":"LOST"}],"groupBy":[{"field":"close-date","bucket":"quarter"}],"metrics":[{"op":"count_distinct","field":"contact-name","as":"customers"},{"op":"min","field":"amount"},{"op":"max","field":"amount"}],"sort":[{"by":"close-date","direction":"DESC"}],"timezone":"Europe/Madrid"}'`,
955
+ raw: `{
956
+ "where": [
957
+ { "field": "status", "op": "neq", "value": "LOST" }
958
+ ],
959
+ "groupBy": [
960
+ { "field": "close-date", "bucket": "quarter" }
961
+ ],
962
+ "metrics": [
963
+ { "op": "count_distinct", "field": "contact-name", "as": "customers" },
964
+ { "op": "min", "field": "amount" },
965
+ { "op": "max", "field": "amount" }
966
+ ],
967
+ "sort": [
968
+ { "by": "close-date", "direction": "DESC" }
969
+ ],
970
+ "timezone": "Europe/Madrid"
808
971
  }`
809
972
  }
810
973
  ],
@@ -1553,8 +1716,8 @@ var specificExamples = {
1553
1716
  }`
1554
1717
  },
1555
1718
  {
1556
- description: "Create a TABLE widget with locked fields: contact-name locked permanently (no conditions) and status locked while invoice-number or amount is empty (--lock-match any), with before/after lock messages.",
1557
- command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type table --name Invoices --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field contact-name --field invoice-number --field status --field amount --lock-field contact-name --lock-condition "status:invoice-number:is_empty" --lock-condition "status:amount:is_empty" --lock-match "status:any" --lock-message-before "status:Status locks while the invoice number or the amount is missing." --lock-message-after "status:Fill in the invoice number and the amount to change the status."`,
1719
+ description: "Create a TABLE widget with locked fields: contact-name locked permanently (no conditions) and, of status, only its Paid option (--lock-option) while invoice-number or amount is empty (--lock-match any), with before/after lock messages. The other status options stay selectable.",
1720
+ command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type table --name Invoices --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field contact-name --field invoice-number --field status --field amount --lock-field contact-name --lock-condition "status:invoice-number:is_empty" --lock-condition "status:amount:is_empty" --lock-match "status:any" --lock-option "status:Paid" --lock-message-before "status:Paid can only be chosen once the invoice number and the amount are set." --lock-message-after "status:Fill in the invoice number and the amount to mark the invoice as Paid."`,
1558
1721
  raw: `{
1559
1722
  "type": "TABLE_OR_SUBTABLE",
1560
1723
  "source": {
@@ -1576,6 +1739,7 @@ var specificExamples = {
1576
1739
  },
1577
1740
  {
1578
1741
  "field": { "fieldId": "status" },
1742
+ "lockedOptions": ["Paid"],
1579
1743
  "conditions": [
1580
1744
  {
1581
1745
  "origin": { "fieldId": "invoice-number" },
@@ -1589,8 +1753,8 @@ var specificExamples = {
1589
1753
  }
1590
1754
  ],
1591
1755
  "conditionMatch": "ANY",
1592
- "messageBeforeLock": "Status locks while the invoice number or the amount is missing.",
1593
- "messageAfterLock": "Fill in the invoice number and the amount to change the status."
1756
+ "messageBeforeLock": "Paid can only be chosen once the invoice number and the amount are set.",
1757
+ "messageAfterLock": "Fill in the invoice number and the amount to mark the invoice as Paid."
1594
1758
  }
1595
1759
  ]
1596
1760
  }
@@ -1982,8 +2146,8 @@ var specificExamples = {
1982
2146
  }`
1983
2147
  },
1984
2148
  {
1985
- description: "Configure locked fields (replaces the stored configuration): contact-name locked permanently, status locked while invoice-number or amount is empty. Empty conditions = always locked; conditions combine with AND unless --lock-match <field>:any locks as soon as one matches. Enforcement happens in display widgets only, never in the database view.",
1986
- command: `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --lock-field contact-name --lock-condition "status:invoice-number:is_empty" --lock-condition "status:amount:is_empty" --lock-match "status:any" --lock-message-before "status:Status locks while the invoice number or the amount is missing." --lock-message-after "status:Fill in the invoice number and the amount to change the status."`,
2149
+ description: "Configure locked fields (replaces the stored configuration): contact-name locked permanently and, of status, only its Paid option while invoice-number or amount is empty. Empty conditions = always locked; conditions combine with AND unless --lock-match <field>:any locks as soon as one matches. --lock-option (option name or id, repeatable) narrows the lock of an option field to those options; the API stores and returns them as option ids. Enforcement happens in display widgets only, never in the database view.",
2150
+ command: `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --lock-field contact-name --lock-condition "status:invoice-number:is_empty" --lock-condition "status:amount:is_empty" --lock-match "status:any" --lock-option "status:Paid" --lock-message-before "status:Paid can only be chosen once the invoice number and the amount are set." --lock-message-after "status:Fill in the invoice number and the amount to mark the invoice as Paid."`,
1987
2151
  raw: `{
1988
2152
  "behavior": {
1989
2153
  "lockedFields": [
@@ -1993,6 +2157,7 @@ var specificExamples = {
1993
2157
  },
1994
2158
  {
1995
2159
  "field": { "fieldId": "status" },
2160
+ "lockedOptions": ["Paid"],
1996
2161
  "conditions": [
1997
2162
  {
1998
2163
  "origin": { "fieldId": "invoice-number" },
@@ -2006,8 +2171,8 @@ var specificExamples = {
2006
2171
  }
2007
2172
  ],
2008
2173
  "conditionMatch": "ANY",
2009
- "messageBeforeLock": "Status locks while the invoice number or the amount is missing.",
2010
- "messageAfterLock": "Fill in the invoice number and the amount to change the status."
2174
+ "messageBeforeLock": "Paid can only be chosen once the invoice number and the amount are set.",
2175
+ "messageAfterLock": "Fill in the invoice number and the amount to mark the invoice as Paid."
2011
2176
  }
2012
2177
  ]
2013
2178
  }
@@ -4536,7 +4701,7 @@ function getCommandExamples(commandName, filters = {}) {
4536
4701
  const examples = commandName === "schemas fields create" ? buildSchemaFieldCreateExamples(filters.type) : specificExamples[commandName] ?? [];
4537
4702
  return examples.map((example) => withResponseEnvelope(example, commandName));
4538
4703
  }
4539
- function withResponseEnvelope(example, commandName) {
4704
+ function withResponseEnvelope({ responseMeta, ...example }, commandName) {
4540
4705
  if (example.response === void 0) {
4541
4706
  return example;
4542
4707
  }
@@ -4548,10 +4713,14 @@ function withResponseEnvelope(example, commandName) {
4548
4713
  }
4549
4714
  return {
4550
4715
  ...example,
4551
- response: JSON.stringify(buildJsonSuccess(payload, { command: commandName }), null, 2)
4716
+ response: JSON.stringify(
4717
+ buildJsonSuccess(payload, { command: commandName, ...responseMeta }),
4718
+ null,
4719
+ 2
4720
+ )
4552
4721
  };
4553
4722
  }
4554
4723
  export {
4555
4724
  getCommandExamples
4556
4725
  };
4557
- //# sourceMappingURL=examples-VXDDPC3X.js.map
4726
+ //# sourceMappingURL=examples-MPBE5OXQ.js.map