sgp-sdk 1.1.3 → 1.2.0

package/README.md

@@ -61,6 +61,7 @@ method and path.
 | `ura.listClients(params?)`                              | `POST /api/ura/clientes/`                               |
 | `ura.lookupCustomer(params)`                            | `POST /api/ura/consultacliente/`                        |
 | `ura.listContracts(params?)`                            | `POST /api/ura/listacontrato/`                          |
+| `ura.listAnnotations(params)` **experimental**          | `GET /api/ura/cliente/anotacao/list/`                   |
 | `ura.listServiceOrders(params?)`                        | `POST /api/ura/ordemservico/list/`                      |
 | `ura.listInvoices(params?)`                             | `POST /api/ura/titulos/`                                |
 | `ura.listPops()`                                        | `POST /api/ura/pops/`                                   |
@@ -92,6 +93,47 @@ not geocode. `lat`, `lng` and `distancia` are always numbers (Geogrid sends them
 and the SDK converts them). A malformed gateway answer, such as a CTO with a non-numeric `lat`, is
 `SCHEMA_MISMATCH`.
 
+### Experimental annotation listing
+
+```ts
+const notes = await sgp.ura.listAnnotations({ cliente_id: 10, contrato_id: 100 });
+```
+
+`ura.listAnnotations` requires at least one of `cliente_id` / `contrato_id`, each a positive safe-integer
+number. Missing filters, nulls, numeric strings and invalid numbers return `VALIDATION` with status 0
+without fetching. Customer-only includes notes with a null contract; contract-only selects that
+contract; both filters mean **AND**, never OR or fallback. No match is a successful empty array.
+
+SGP currently ignores these upstream filters (vendor defect reported, not claimed fixed). The SDK
+still sends canonical filters in one authenticated GET and selects raw identities **before** parsing
+selected notes. A definite mismatch excludes a row even if unrelated content is malformed. If a
+needed identity is missing or malformed and no definite mismatch excludes it, the call fails with
+`SCHEMA_MISMATCH`, not partial data. Source identity strings are not coerced. Selected core fields
+are strict; optional-field drift produces ordinary, selected-only schema warnings. Source order and
+duplicates are preserved; unknown fields are stripped.
+
+Returns matching notes present in one SGP response; source completeness is not guaranteed while this method is experimental.
+No documented pagination contract proves completeness; there is no automatic paging, retry, polling,
+cache, completeness flag or operational warning. The method, snake_case params and array-shaped
+`SgpResult<ListAnnotationsResponse>` remain usable after the vendor fix; local selection and
+validation remain as defense. Removing the experimental label requires evidence of corrected behavior.
+
+The nine declared fields are required numeric `id` / `cliente`, required number-or-null
+`clientecontrato`, required string `anotacao`, optional/nullable numeric `usuario` / `tipo` /
+`alerta_modo`, and optional/nullable string `data_cadastro` / `data_alteracao`. Text and dates are
+preserved verbatim, without HTML rendering, trimming or date parsing. `annotationPersonalKeys`
+classifies note text and staff identity (`anotacao`, `usuario`); `annotationSecretKeys` is empty.
+Use `omitSensitive(note, annotationPersonalKeys)` before logging or forwarding: free text may contain
+user-entered sensitive content even though no credential field is declared.
+
+**Trusted server only:** the multi-customer upstream body enters SDK memory, but the SDK never
+returns, logs or caches the bulk array. Injected fetch, tracing and other instrumentation see the
+body **before** SDK selection and MUST NOT capture it. Local selection is not an authorization
+boundary: the application must authorize requested IDs and keep credentials and execution trusted.
+SDK-generated diagnostics contain paths/types, not source values. Existing upstream error details
+are unchanged and may echo request values; treat them as sensitive too. This special filtered read
+is deliberately excluded from the generic filterless probe registry.
+
 ## Result and error contract
 
 Every method returns `SgpResult<T>`:

package/dist/client.d.ts

@@ -8,6 +8,7 @@ import { type ListSellersResponse } from "./endpoints/precadastro/list-sellers.j
 import { type AddCustomerDocumentParams, type AddCustomerDocumentResponse } from "./endpoints/suporte/add-customer-document.js";
 import { type ListCustomerDocumentsResponse } from "./endpoints/suporte/list-customer-documents.js";
 import { type CheckCoverageParams, type CheckCoverageResponse } from "./endpoints/ura/check-coverage.js";
+import { type ListAnnotationsParams, type ListAnnotationsResponse } from "./endpoints/ura/list-annotations.js";
 import { type ListClientsParams, type ListClientsResponse } from "./endpoints/ura/list-clients.js";
 import { type ListContractsParams, type ListContractsResponse } from "./endpoints/ura/list-contracts.js";
 import { type ListInvoicesParams, type ListInvoicesResponse } from "./endpoints/ura/list-invoices.js";
@@ -23,6 +24,16 @@ import type { SgpResult, SgpWriteResult } from "./result.js";
 import type { SgpClientConfig, SgpFile } from "./transport.js";
 /** Methods that hit the `/api/ura/` routes. All are reads, except `openTicket`: a write that returns an {@link SgpWriteResult}. */
 export interface UraClient {
+    /**
+     * @experimental Lists annotations: `GET /api/ura/cliente/anotacao/list/`, with local identity selection.
+     * Requires positive safe-integer `cliente_id` and/or `contrato_id`; both mean AND.
+     * Returns matching notes present in one SGP response; source completeness is not guaranteed while this method is experimental.
+     * The bulk upstream body enters SDK memory but is never returned, logged or cached by the SDK.
+     * Use only on a trusted server; authorize requested IDs. Injected fetch/tracing must not capture
+     * the upstream body. Omit note text/staff identity with `annotationPersonalKeys` before logging.
+     * The public API and local validation/selection remain when upstream filtering is fixed.
+     */
+    listAnnotations: (params: ListAnnotationsParams) => Promise<SgpResult<ListAnnotationsResponse>>;
     /**
      * Lists clients, one page at a time: `POST /api/ura/clientes/`.
      *

package/dist/endpoints/ura/list-annotations.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import type { SgpResult } from "../../result.js";
+import { type SgpClientConfig } from "../../transport.js";
+/** Parsed, locally selected annotations; unknown fields are stripped. */
+export declare const listAnnotationsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    cliente: z.ZodNumber;
+    clientecontrato: z.ZodNullable<z.ZodNumber>;
+    anotacao: z.ZodString;
+    usuario: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    tipo: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    alerta_modo: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    data_cadastro: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    data_alteracao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>>;
+/** Required strict fields of each selected annotation. */
+export declare const listAnnotationsKeyFields: readonly ["[].id", "[].cliente", "[].clientecontrato", "[].anotacao"];
+/** Normalized path of each annotation in the root array. */
+export declare const annotationItemPath = "[]";
+/** No declared credential fields; free text can still contain sensitive content. */
+export declare const annotationSecretKeys: readonly [];
+/** Free text and staff identity must be omitted before logging or forwarding. */
+export declare const annotationPersonalKeys: readonly ["anotacao", "usuario"];
+/** At least one positive safe-integer filter is required; both filters mean AND. */
+export interface ListAnnotationsParams {
+    cliente_id?: number;
+    contrato_id?: number;
+}
+/** Selected notes present in one SGP response, not a guarantee of source completeness. */
+export type ListAnnotationsResponse = z.output<typeof listAnnotationsSchema>;
+/** Special read: never add to the generic filterless probe registry. */
+export declare const listAnnotations: (config: SgpClientConfig, params: ListAnnotationsParams) => Promise<SgpResult<ListAnnotationsResponse>>;

package/dist/index.d.ts

@@ -21,6 +21,8 @@ export type { ListCustomerDocumentsResponse } from "./endpoints/suporte/list-cus
 export { customerDocumentItemPath, customerDocumentPersonalKeys, customerDocumentSecretKeys, listCustomerDocumentsDefinition, listCustomerDocumentsKeyFields, } from "./endpoints/suporte/list-customer-documents.js";
 export type { CheckCoverageParams, CheckCoverageResponse, } from "./endpoints/ura/check-coverage.js";
 export { checkCoverageDefinition, checkCoverageKeyFields, coverageItemPath, coveragePersonalKeys, coverageSecretKeys, } from "./endpoints/ura/check-coverage.js";
+export type { ListAnnotationsParams, ListAnnotationsResponse, } from "./endpoints/ura/list-annotations.js";
+export { annotationItemPath, annotationPersonalKeys, annotationSecretKeys, listAnnotationsKeyFields, listAnnotationsSchema, } from "./endpoints/ura/list-annotations.js";
 export type { ListClientsParams, ListClientsResponse } from "./endpoints/ura/list-clients.js";
 export { clientItemPath, clientPersonalKeys, clientSecretKeys, listClientsDefinition, listClientsKeyFields, } from "./endpoints/ura/list-clients.js";
 export type { ListContractsParams, ListContractsResponse, } from "./endpoints/ura/list-contracts.js";

package/dist/index.js

@@ -633,45 +633,115 @@ var checkCoverageDefinition = {
   personalKeys: coveragePersonalKeys
 };
 
-// src/endpoints/ura/list-clients.ts
+// src/endpoints/ura/list-annotations.ts
 import { z as z11 } from "zod";
-var addressSchema = z11.object({
-  logradouro: z11.string().optional().nullable(),
-  numero: z11.number().optional().nullable(),
-  bairro: z11.string().optional().nullable(),
-  cidade: z11.string().optional().nullable(),
-  uf: z11.string().optional().nullable(),
-  cep: z11.string().optional().nullable(),
-  complemento: z11.string().optional().nullable(),
-  latitude: z11.string().optional().nullable(),
-  longitude: z11.string().optional().nullable()
+var PATH = "/api/ura/cliente/anotacao/list/";
+var annotationSchema = z11.object({
+  id: z11.number(),
+  cliente: z11.number(),
+  clientecontrato: z11.number().nullable(),
+  anotacao: z11.string(),
+  usuario: z11.number().optional().nullable(),
+  tipo: z11.number().optional().nullable(),
+  alerta_modo: z11.number().optional().nullable(),
+  data_cadastro: z11.string().optional().nullable(),
+  data_alteracao: z11.string().optional().nullable()
+});
+var listAnnotationsSchema = z11.array(annotationSchema);
+var listAnnotationsKeyFields = [
+  "[].id",
+  "[].cliente",
+  "[].clientecontrato",
+  "[].anotacao"
+];
+var annotationItemPath = "[]";
+var annotationSecretKeys = [];
+var annotationPersonalKeys = ["anotacao", "usuario"];
+var validFilter = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+var listAnnotations = async (config, params) => {
+  const customer = params?.cliente_id;
+  const contract = params?.contrato_id;
+  if (customer === undefined && contract === undefined || customer !== undefined && !validFilter(customer) || contract !== undefined && !validFilter(contract)) {
+    return {
+      success: false,
+      error: createError("VALIDATION", 0, PATH, "cliente_id / contrato_id: supply at least one positive safe integer", MESSAGE_REJECTED_LOCALLY)
+    };
+  }
+  const raw = await sendRequest(config, {
+    method: "GET",
+    path: PATH,
+    params: { cliente_id: customer, contrato_id: contract }
+  });
+  if (!raw.ok)
+    return { success: false, error: raw.error };
+  if (!Array.isArray(raw.body)) {
+    return { success: false, error: createError("SCHEMA_MISMATCH", 200, PATH, "(root)") };
+  }
+  const rows = raw.body;
+  const selected = [];
+  for (const row of rows) {
+    const record = typeof row === "object" && row !== null && !Array.isArray(row) ? row : {};
+    const customerIsNumber = typeof record.cliente === "number" && Number.isFinite(record.cliente);
+    const contractIsNumber = typeof record.clientecontrato === "number" && Number.isFinite(record.clientecontrato);
+    const customerMismatch = customer !== undefined && customerIsNumber && record.cliente !== customer;
+    const contractMismatch = contract !== undefined && (record.clientecontrato === null || contractIsNumber && record.clientecontrato !== contract);
+    if (customerMismatch || contractMismatch)
+      continue;
+    const ambiguousPaths = [];
+    if (customer !== undefined && !customerIsNumber)
+      ambiguousPaths.push("[].cliente");
+    if (contract !== undefined && !contractIsNumber)
+      ambiguousPaths.push("[].clientecontrato");
+    if (ambiguousPaths.length > 0) {
+      return {
+        success: false,
+        error: createError("SCHEMA_MISMATCH", 200, PATH, ambiguousPaths.join(", "))
+      };
+    }
+    selected.push(row);
+  }
+  return parseResponse(listAnnotationsSchema, listAnnotationsKeyFields, selected, PATH);
+};
+
+// src/endpoints/ura/list-clients.ts
+import { z as z12 } from "zod";
+var addressSchema = z12.object({
+  logradouro: z12.string().optional().nullable(),
+  numero: z12.number().optional().nullable(),
+  bairro: z12.string().optional().nullable(),
+  cidade: z12.string().optional().nullable(),
+  uf: z12.string().optional().nullable(),
+  cep: z12.string().optional().nullable(),
+  complemento: z12.string().optional().nullable(),
+  latitude: z12.string().optional().nullable(),
+  longitude: z12.string().optional().nullable()
 });
-var contactsSchema = z11.object({
-  telefones: z11.array(z11.string()).optional().nullable(),
-  celulares: z11.array(z11.string()).optional().nullable(),
-  emails: z11.array(z11.string()).optional().nullable(),
-  outros: z11.array(z11.string()).optional().nullable()
+var contactsSchema = z12.object({
+  telefones: z12.array(z12.string()).optional().nullable(),
+  celulares: z12.array(z12.string()).optional().nullable(),
+  emails: z12.array(z12.string()).optional().nullable(),
+  outros: z12.array(z12.string()).optional().nullable()
 });
-var clientSchema = z11.object({
-  id: z11.number(),
-  nome: z11.string(),
-  tipo: z11.string(),
-  cpfcnpj: z11.string(),
-  sexo: z11.string().optional().nullable(),
-  dataCadastro: z11.string().optional().nullable(),
+var clientSchema = z12.object({
+  id: z12.number(),
+  nome: z12.string(),
+  tipo: z12.string(),
+  cpfcnpj: z12.string(),
+  sexo: z12.string().optional().nullable(),
+  dataCadastro: z12.string().optional().nullable(),
   endereco: addressSchema.optional().nullable(),
-  contratos: z11.array(z11.object({})).optional().nullable(),
-  titulos: z11.array(z11.object({})).optional().nullable(),
+  contratos: z12.array(z12.object({})).optional().nullable(),
+  titulos: z12.array(z12.object({})).optional().nullable(),
   contatos: contactsSchema.optional().nullable()
 });
-var listClientsSchema = z11.object({
-  paginacao: z11.object({
-    offset: z11.number().optional().nullable(),
-    limit: z11.number().optional().nullable(),
-    parcial: z11.number().optional().nullable(),
-    total: z11.number()
+var listClientsSchema = z12.object({
+  paginacao: z12.object({
+    offset: z12.number().optional().nullable(),
+    limit: z12.number().optional().nullable(),
+    parcial: z12.number().optional().nullable(),
+    total: z12.number()
   }),
-  clientes: z11.array(clientSchema)
+  clientes: z12.array(clientSchema)
 });
 var listClientsKeyFields = [
   "paginacao.total",
@@ -695,21 +765,21 @@ var listClientsDefinition = {
 };
 
 // src/endpoints/ura/list-contracts.ts
-import { z as z12 } from "zod";
-var contractSummarySchema = z12.object({
-  id_contrato: z12.number(),
-  id_cliente: z12.number(),
-  status: z12.string(),
-  pop_id: z12.number(),
-  nome: z12.string().optional().nullable(),
-  cpfcnpj: z12.string().optional().nullable(),
-  email: z12.string().optional().nullable(),
-  telefone: z12.string().optional().nullable(),
-  data_status: z12.string().optional().nullable(),
-  data_cadastro: z12.string().optional().nullable(),
-  motivo_status: z12.string().optional().nullable()
+import { z as z13 } from "zod";
+var contractSummarySchema = z13.object({
+  id_contrato: z13.number(),
+  id_cliente: z13.number(),
+  status: z13.string(),
+  pop_id: z13.number(),
+  nome: z13.string().optional().nullable(),
+  cpfcnpj: z13.string().optional().nullable(),
+  email: z13.string().optional().nullable(),
+  telefone: z13.string().optional().nullable(),
+  data_status: z13.string().optional().nullable(),
+  data_cadastro: z13.string().optional().nullable(),
+  motivo_status: z13.string().optional().nullable()
 });
-var listContractsSchema = z12.array(contractSummarySchema);
+var listContractsSchema = z13.array(contractSummarySchema);
 var listContractsKeyFields = [
   "[].id_contrato",
   "[].id_cliente",
@@ -736,46 +806,46 @@ var listContractsDefinition = {
 };
 
 // src/endpoints/ura/list-invoices.ts
-import { z as z13 } from "zod";
-var invoiceSchema = z13.object({
-  id: z13.number(),
-  status: z13.string(),
-  valor: z13.number(),
-  dataVencimento: z13.string(),
-  clienteNome: z13.string().optional().nullable(),
-  clienteCpfcnpj: z13.string().optional().nullable(),
-  clienteContrato: z13.number().optional().nullable(),
-  portador: z13.string().optional().nullable(),
-  numeroDocumento: z13.number().optional().nullable(),
-  nossoNumero: z13.string().optional().nullable(),
-  link: z13.string().optional().nullable(),
-  link_cobranca: z13.string().optional().nullable(),
-  valorDesconto: z13.number().optional().nullable(),
-  valorCorrigido: z13.number().optional().nullable(),
-  valorPago: z13.number().optional().nullable(),
-  valorPagoParcial: z13.number().optional().nullable(),
-  codigoBarras: z13.string().optional().nullable(),
-  linhaDigitavel: z13.string().optional().nullable(),
-  codigoPix: z13.string().optional().nullable(),
-  dataEmissao: z13.string().optional().nullable(),
-  dataPagamento: z13.string().optional().nullable(),
-  dataCancelamento: z13.string().optional().nullable(),
-  demonstrativo: z13.string().optional().nullable(),
-  acordoPagamento: z13.object({
-    acordados: z13.array(z13.object({})).optional().nullable(),
-    cobrados: z13.array(z13.object({})).optional().nullable()
+import { z as z14 } from "zod";
+var invoiceSchema = z14.object({
+  id: z14.number(),
+  status: z14.string(),
+  valor: z14.number(),
+  dataVencimento: z14.string(),
+  clienteNome: z14.string().optional().nullable(),
+  clienteCpfcnpj: z14.string().optional().nullable(),
+  clienteContrato: z14.number().optional().nullable(),
+  portador: z14.string().optional().nullable(),
+  numeroDocumento: z14.number().optional().nullable(),
+  nossoNumero: z14.string().optional().nullable(),
+  link: z14.string().optional().nullable(),
+  link_cobranca: z14.string().optional().nullable(),
+  valorDesconto: z14.number().optional().nullable(),
+  valorCorrigido: z14.number().optional().nullable(),
+  valorPago: z14.number().optional().nullable(),
+  valorPagoParcial: z14.number().optional().nullable(),
+  codigoBarras: z14.string().optional().nullable(),
+  linhaDigitavel: z14.string().optional().nullable(),
+  codigoPix: z14.string().optional().nullable(),
+  dataEmissao: z14.string().optional().nullable(),
+  dataPagamento: z14.string().optional().nullable(),
+  dataCancelamento: z14.string().optional().nullable(),
+  demonstrativo: z14.string().optional().nullable(),
+  acordoPagamento: z14.object({
+    acordados: z14.array(z14.object({})).optional().nullable(),
+    cobrados: z14.array(z14.object({})).optional().nullable()
   }).optional().nullable(),
-  formaPagamento: z13.string().optional().nullable(),
-  usuario_baixa: z13.string().optional().nullable()
+  formaPagamento: z14.string().optional().nullable(),
+  usuario_baixa: z14.string().optional().nullable()
 });
-var listInvoicesSchema = z13.object({
-  paginacao: z13.object({
-    offset: z13.number().optional().nullable(),
-    limit: z13.number().optional().nullable(),
-    parcial: z13.number().optional().nullable(),
-    total: z13.number()
+var listInvoicesSchema = z14.object({
+  paginacao: z14.object({
+    offset: z14.number().optional().nullable(),
+    limit: z14.number().optional().nullable(),
+    parcial: z14.number().optional().nullable(),
+    total: z14.number()
   }),
-  titulos: z13.array(invoiceSchema)
+  titulos: z14.array(invoiceSchema)
 });
 var listInvoicesKeyFields = [
   "paginacao.total",
@@ -806,23 +876,23 @@ var listInvoicesDefinition = {
 };
 
 // src/endpoints/ura/list-nas.ts
-import { z as z14 } from "zod";
-var nasPopSchema = z14.object({
-  id: z14.number().optional().nullable(),
-  cidade: z14.string().optional().nullable(),
-  uf: z14.string().optional().nullable(),
-  codigo_ibge: z14.number().optional().nullable(),
-  ativo: z14.boolean().optional().nullable()
+import { z as z15 } from "zod";
+var nasPopSchema = z15.object({
+  id: z15.number().optional().nullable(),
+  cidade: z15.string().optional().nullable(),
+  uf: z15.string().optional().nullable(),
+  codigo_ibge: z15.number().optional().nullable(),
+  ativo: z15.boolean().optional().nullable()
 });
-var nasSchema = z14.object({
-  id: z14.number(),
-  descricao: z14.string(),
-  identificador: z14.string(),
-  endereco_ip: z14.string().optional().nullable(),
-  ativo: z14.boolean().optional().nullable(),
-  pops: z14.array(nasPopSchema).optional().nullable()
+var nasSchema = z15.object({
+  id: z15.number(),
+  descricao: z15.string(),
+  identificador: z15.string(),
+  endereco_ip: z15.string().optional().nullable(),
+  ativo: z15.boolean().optional().nullable(),
+  pops: z15.array(nasPopSchema).optional().nullable()
 });
-var listNasSchema = z14.array(nasSchema);
+var listNasSchema = z15.array(nasSchema);
 var listNasKeyFields = ["[].id", "[].descricao", "[].identificador"];
 var nasItemPath = "[]";
 var nasSecretKeys = ["endereco_ip"];
@@ -838,12 +908,12 @@ var listNasDefinition = {
 };
 
 // src/endpoints/ura/list-occurrence-methods.ts
-import { z as z15 } from "zod";
-var occurrenceMethodSchema = z15.object({
-  codigo: z15.number(),
-  descricao: z15.string()
+import { z as z16 } from "zod";
+var occurrenceMethodSchema = z16.object({
+  codigo: z16.number(),
+  descricao: z16.string()
 });
-var listOccurrenceMethodsSchema = z15.array(occurrenceMethodSchema);
+var listOccurrenceMethodsSchema = z16.array(occurrenceMethodSchema);
 var listOccurrenceMethodsKeyFields = ["[].codigo", "[].descricao"];
 var occurrenceMethodItemPath = "[]";
 var occurrenceMethodSecretKeys = [];
@@ -859,13 +929,13 @@ var listOccurrenceMethodsDefinition = {
 };
 
 // src/endpoints/ura/list-payment-carriers.ts
-import { z as z16 } from "zod";
-var paymentCarrierSchema = z16.object({
-  id: z16.number(),
-  descricao: z16.string(),
-  codigo_banco: z16.string().optional().nullable()
+import { z as z17 } from "zod";
+var paymentCarrierSchema = z17.object({
+  id: z17.number(),
+  descricao: z17.string(),
+  codigo_banco: z17.string().optional().nullable()
 });
-var listPaymentCarriersSchema = z16.array(paymentCarrierSchema);
+var listPaymentCarriersSchema = z17.array(paymentCarrierSchema);
 var listPaymentCarriersKeyFields = ["[].id", "[].descricao"];
 var paymentCarrierItemPath = "[]";
 var paymentCarrierSecretKeys = [];
@@ -881,63 +951,63 @@ var listPaymentCarriersDefinition = {
 };
 
 // src/endpoints/ura/list-plans.ts
-import { z as z17 } from "zod";
-var planPopSchema = z17.object({
-  id: z17.number().optional().nullable(),
-  uf: z17.string().optional().nullable(),
-  pop: z17.string().optional().nullable()
+import { z as z18 } from "zod";
+var planPopSchema = z18.object({
+  id: z18.number().optional().nullable(),
+  uf: z18.string().optional().nullable(),
+  pop: z18.string().optional().nullable()
 });
-var planSchema = z17.object({
-  id: z17.number(),
-  descricao: z17.string(),
-  preco: z17.number(),
-  ativo: z17.boolean(),
-  grupo: z17.string().optional().nullable(),
-  tipo: z17.string().optional().nullable(),
-  pos_pago: z17.boolean().optional().nullable(),
-  desconto: z17.number().optional().nullable(),
-  desconto_venc: z17.number().optional().nullable(),
-  desconto_venc_modo: z17.string().optional().nullable(),
-  valor_desconto_temporario: z17.number().optional().nullable(),
-  desconto_temporario_modo: z17.string().optional().nullable(),
-  desconto_temporario_quantidade: z17.number().optional().nullable(),
-  descricao_desconto_temporario: z17.string().optional().nullable(),
-  desconto_temporario_proporcional: z17.boolean().optional().nullable(),
-  observacao: z17.string().optional().nullable(),
-  instalacao_qtd_parcelas: z17.number().optional().nullable(),
-  instalacao_valor: z17.number().optional().nullable(),
-  instalacao_desconto_max: z17.number().optional().nullable(),
-  instalacao_desconto_min: z17.number().optional().nullable(),
-  disponivel_pre_cadastro: z17.boolean().optional().nullable(),
-  disponivel_pre_cadastro_publico: z17.boolean().optional().nullable(),
-  data_validade: z17.string().optional().nullable(),
-  pops: z17.array(planPopSchema).optional().nullable(),
-  auto_bloqueio: z17.boolean().optional().nullable(),
-  dias_bloqueio_pos_venc: z17.number().optional().nullable(),
-  dias_bloqueio_aviso: z17.number().optional().nullable(),
-  dias_reducao_velocidade: z17.number().optional().nullable(),
-  download: z17.number().optional().nullable(),
-  upload: z17.number().optional().nullable(),
-  trafego_mensal: z17.number().optional().nullable(),
-  contabilizacao_trafego_mensal: z17.string().optional().nullable(),
-  trafego_excedente_acao: z17.string().optional().nullable(),
-  valor_trafego_excedido: z17.number().optional().nullable(),
-  duplicacao_noturna: z17.boolean().optional().nullable(),
-  inicio_duplicacao_noturna: z17.string().optional().nullable(),
-  fim_duplicacao_noturna: z17.string().optional().nullable(),
-  modo_velocidade_reduzida: z17.string().optional().nullable(),
-  download_red_financeiro: z17.number().optional().nullable(),
-  upload_red_financeiro: z17.number().optional().nullable(),
-  modo_velocidade_red_franquia: z17.string().optional().nullable(),
-  download_red_franquia: z17.number().optional().nullable(),
-  upload_red_franquia: z17.number().optional().nullable(),
-  combo: z17.array(z17.object({})).optional().nullable(),
-  qtd_servicos: z17.number().optional().nullable()
+var planSchema = z18.object({
+  id: z18.number(),
+  descricao: z18.string(),
+  preco: z18.number(),
+  ativo: z18.boolean(),
+  grupo: z18.string().optional().nullable(),
+  tipo: z18.string().optional().nullable(),
+  pos_pago: z18.boolean().optional().nullable(),
+  desconto: z18.number().optional().nullable(),
+  desconto_venc: z18.number().optional().nullable(),
+  desconto_venc_modo: z18.string().optional().nullable(),
+  valor_desconto_temporario: z18.number().optional().nullable(),
+  desconto_temporario_modo: z18.string().optional().nullable(),
+  desconto_temporario_quantidade: z18.number().optional().nullable(),
+  descricao_desconto_temporario: z18.string().optional().nullable(),
+  desconto_temporario_proporcional: z18.boolean().optional().nullable(),
+  observacao: z18.string().optional().nullable(),
+  instalacao_qtd_parcelas: z18.number().optional().nullable(),
+  instalacao_valor: z18.number().optional().nullable(),
+  instalacao_desconto_max: z18.number().optional().nullable(),
+  instalacao_desconto_min: z18.number().optional().nullable(),
+  disponivel_pre_cadastro: z18.boolean().optional().nullable(),
+  disponivel_pre_cadastro_publico: z18.boolean().optional().nullable(),
+  data_validade: z18.string().optional().nullable(),
+  pops: z18.array(planPopSchema).optional().nullable(),
+  auto_bloqueio: z18.boolean().optional().nullable(),
+  dias_bloqueio_pos_venc: z18.number().optional().nullable(),
+  dias_bloqueio_aviso: z18.number().optional().nullable(),
+  dias_reducao_velocidade: z18.number().optional().nullable(),
+  download: z18.number().optional().nullable(),
+  upload: z18.number().optional().nullable(),
+  trafego_mensal: z18.number().optional().nullable(),
+  contabilizacao_trafego_mensal: z18.string().optional().nullable(),
+  trafego_excedente_acao: z18.string().optional().nullable(),
+  valor_trafego_excedido: z18.number().optional().nullable(),
+  duplicacao_noturna: z18.boolean().optional().nullable(),
+  inicio_duplicacao_noturna: z18.string().optional().nullable(),
+  fim_duplicacao_noturna: z18.string().optional().nullable(),
+  modo_velocidade_reduzida: z18.string().optional().nullable(),
+  download_red_financeiro: z18.number().optional().nullable(),
+  upload_red_financeiro: z18.number().optional().nullable(),
+  modo_velocidade_red_franquia: z18.string().optional().nullable(),
+  download_red_franquia: z18.number().optional().nullable(),
+  upload_red_franquia: z18.number().optional().nullable(),
+  combo: z18.array(z18.object({})).optional().nullable(),
+  qtd_servicos: z18.number().optional().nullable()
 });
-var listPlansSchema = z17.object({
-  planos: z17.array(planSchema),
-  total_planos: z17.number().optional().nullable(),
-  total_qtd_servicos: z17.number().optional().nullable()
+var listPlansSchema = z18.object({
+  planos: z18.array(planSchema),
+  total_planos: z18.number().optional().nullable(),
+  total_qtd_servicos: z18.number().optional().nullable()
 });
 var listPlansKeyFields = [
   "planos",
@@ -960,12 +1030,12 @@ var listPlansDefinition = {
 };
 
 // src/endpoints/ura/list-pops.ts
-import { z as z18 } from "zod";
-var popSchema = z18.object({
-  id: z18.number(),
-  pop: z18.string()
+import { z as z19 } from "zod";
+var popSchema = z19.object({
+  id: z19.number(),
+  pop: z19.string()
 });
-var listPopsSchema = z18.array(popSchema);
+var listPopsSchema = z19.array(popSchema);
 var listPopsKeyFields = ["[].id", "[].pop"];
 var popItemPath = "[]";
 var popSecretKeys = [];
@@ -981,41 +1051,41 @@ var listPopsDefinition = {
 };
 
 // src/endpoints/ura/list-service-orders.ts
-import { z as z19 } from "zod";
-var serviceOrderSchema = z19.object({
-  id: z19.number(),
-  contrato: z19.number(),
-  status_id: z19.number(),
-  status: z19.string(),
-  tipo_id: z19.number(),
-  data_cadastro: z19.string(),
-  cliente: z19.string().optional().nullable(),
-  contrato_status: z19.string().optional().nullable(),
-  contrato_status_id: z19.number().optional().nullable(),
-  ocorrencia: z19.string().optional().nullable(),
-  hora_cadastro: z19.string().optional().nullable(),
-  data_agendamento: z19.string().optional().nullable(),
-  hora_agendamento: z19.string().optional().nullable(),
-  data_finalizacao: z19.string().optional().nullable(),
-  hora_finalizacao: z19.string().optional().nullable(),
-  tipo: z19.string().optional().nullable(),
-  motivo: z19.string().optional().nullable(),
-  pop: z19.string().optional().nullable(),
-  conteudo: z19.string().optional().nullable(),
-  responsavel: z19.string().optional().nullable(),
-  tecnicos_auxiliares: z19.array(z19.object({})).optional().nullable(),
-  usuario: z19.string().optional().nullable(),
-  usuario_finalizacao: z19.string().optional().nullable(),
-  classificacoes: z19.array(z19.object({})).optional().nullable()
+import { z as z20 } from "zod";
+var serviceOrderSchema = z20.object({
+  id: z20.number(),
+  contrato: z20.number(),
+  status_id: z20.number(),
+  status: z20.string(),
+  tipo_id: z20.number(),
+  data_cadastro: z20.string(),
+  cliente: z20.string().optional().nullable(),
+  contrato_status: z20.string().optional().nullable(),
+  contrato_status_id: z20.number().optional().nullable(),
+  ocorrencia: z20.string().optional().nullable(),
+  hora_cadastro: z20.string().optional().nullable(),
+  data_agendamento: z20.string().optional().nullable(),
+  hora_agendamento: z20.string().optional().nullable(),
+  data_finalizacao: z20.string().optional().nullable(),
+  hora_finalizacao: z20.string().optional().nullable(),
+  tipo: z20.string().optional().nullable(),
+  motivo: z20.string().optional().nullable(),
+  pop: z20.string().optional().nullable(),
+  conteudo: z20.string().optional().nullable(),
+  responsavel: z20.string().optional().nullable(),
+  tecnicos_auxiliares: z20.array(z20.object({})).optional().nullable(),
+  usuario: z20.string().optional().nullable(),
+  usuario_finalizacao: z20.string().optional().nullable(),
+  classificacoes: z20.array(z20.object({})).optional().nullable()
 });
-var listServiceOrdersSchema = z19.object({
-  paginacao: z19.object({
-    offset: z19.number().optional().nullable(),
-    limit: z19.number().optional().nullable(),
-    parcial: z19.number().optional().nullable(),
-    total: z19.number()
+var listServiceOrdersSchema = z20.object({
+  paginacao: z20.object({
+    offset: z20.number().optional().nullable(),
+    limit: z20.number().optional().nullable(),
+    parcial: z20.number().optional().nullable(),
+    total: z20.number()
   }),
-  ordens_servicos: z19.array(serviceOrderSchema)
+  ordens_servicos: z20.array(serviceOrderSchema)
 });
 var listServiceOrdersKeyFields = [
   "paginacao.total",
@@ -1041,84 +1111,84 @@ var listServiceOrdersDefinition = {
 };
 
 // src/endpoints/ura/lookup-customer.ts
-import { z as z20 } from "zod";
-var contactEntrySchema = z20.object({
-  inscricoes: z20.array(z20.string()).optional().nullable(),
-  tipoContato: z20.string().optional().nullable(),
-  contato: z20.string().optional().nullable()
+import { z as z21 } from "zod";
+var contactEntrySchema = z21.object({
+  inscricoes: z21.array(z21.string()).optional().nullable(),
+  tipoContato: z21.string().optional().nullable(),
+  contato: z21.string().optional().nullable()
 });
-var tagSchema = z20.object({
-  color: z20.string().optional().nullable(),
-  font: z20.string().optional().nullable(),
-  tag: z20.string().optional().nullable(),
-  id: z20.number().optional().nullable(),
-  categoria_id: z20.number().optional().nullable()
+var tagSchema = z21.object({
+  color: z21.string().optional().nullable(),
+  font: z21.string().optional().nullable(),
+  tag: z21.string().optional().nullable(),
+  id: z21.number().optional().nullable(),
+  categoria_id: z21.number().optional().nullable()
 });
-var loyaltySchema = z20.object({
-  data_inicio: z20.string().optional().nullable(),
-  descricao: z20.string().optional().nullable(),
-  data_fim: z20.string().optional().nullable()
+var loyaltySchema = z21.object({
+  data_inicio: z21.string().optional().nullable(),
+  descricao: z21.string().optional().nullable(),
+  data_fim: z21.string().optional().nullable()
 });
-var customerContractSchema = z20.object({
-  contratoId: z20.number(),
-  clienteId: z20.number(),
-  contratoStatus: z20.number(),
-  contratoStatusDisplay: z20.string(),
-  contratoValorAberto: z20.number(),
-  contratoTitulosAReceber: z20.number(),
-  cobVencimento: z20.number(),
-  contratoStatusModo: z20.number().optional().nullable(),
-  motivo_status: z20.string().optional().nullable(),
-  dataCadastro: z20.string().optional().nullable(),
-  dataAlteracao: z20.string().optional().nullable(),
-  popId: z20.number().optional().nullable(),
-  popNome: z20.string().optional().nullable(),
-  cobPermuta: z20.boolean().optional().nullable(),
-  cobIsento: z20.number().optional().nullable(),
-  promessasPagamentoMes: z20.number().optional().nullable(),
-  link_quitacao: z20.string().optional().nullable(),
-  planointernet: z20.string().optional().nullable(),
+var customerContractSchema = z21.object({
+  contratoId: z21.number(),
+  clienteId: z21.number(),
+  contratoStatus: z21.number(),
+  contratoStatusDisplay: z21.string(),
+  contratoValorAberto: z21.number(),
+  contratoTitulosAReceber: z21.number(),
+  cobVencimento: z21.number(),
+  contratoStatusModo: z21.number().optional().nullable(),
+  motivo_status: z21.string().optional().nullable(),
+  dataCadastro: z21.string().optional().nullable(),
+  dataAlteracao: z21.string().optional().nullable(),
+  popId: z21.number().optional().nullable(),
+  popNome: z21.string().optional().nullable(),
+  cobPermuta: z21.boolean().optional().nullable(),
+  cobIsento: z21.number().optional().nullable(),
+  promessasPagamentoMes: z21.number().optional().nullable(),
+  link_quitacao: z21.string().optional().nullable(),
+  planointernet: z21.string().optional().nullable(),
   fidelidade: loyaltySchema.optional().nullable(),
-  contrato_unificado_principal: z20.number().optional().nullable(),
-  contrato_unificado_filhos: z20.array(z20.number()).optional().nullable(),
-  tags: z20.array(tagSchema).optional().nullable(),
-  anotacoes: z20.array(z20.object({})).optional().nullable(),
-  contratoCentralLogin: z20.string().optional().nullable(),
-  contratoCentralSenha: z20.string().optional().nullable(),
-  servico_login: z20.string().optional().nullable(),
-  servico_senha: z20.string().optional().nullable(),
-  servico_plano: z20.string().optional().nullable(),
-  servico_grupo: z20.string().optional().nullable(),
-  servico_tipo_conexao: z20.string().optional().nullable(),
-  servico_vlan: z20.string().optional().nullable(),
-  servico_mac: z20.string().optional().nullable(),
-  servico_mac2: z20.string().optional().nullable(),
-  servico_wifi_ssid: z20.string().optional().nullable(),
-  servico_wifi_ssid_5: z20.string().optional().nullable(),
-  servico_wifi_password: z20.string().optional().nullable(),
-  servico_wifi_password_5: z20.string().optional().nullable(),
-  servico_wifi_channel: z20.string().optional().nullable(),
-  servico_wifi_channel_5: z20.string().optional().nullable(),
-  razaoSocial: z20.string().optional().nullable(),
-  cpfCnpj: z20.string().optional().nullable(),
-  dataNascimento: z20.string().optional().nullable(),
-  telefones: z20.array(contactEntrySchema).optional().nullable(),
-  telefones_cargos: z20.array(z20.object({})).optional().nullable(),
-  emails: z20.array(contactEntrySchema).optional().nullable(),
-  outros: z20.array(z20.object({})).optional().nullable(),
-  endereco_logradouro: z20.string().optional().nullable(),
-  endereco_numero: z20.number().optional().nullable(),
-  endereco_complemento: z20.string().optional().nullable(),
-  endereco_bairro: z20.string().optional().nullable(),
-  endereco_cidade: z20.string().optional().nullable(),
-  endereco_uf: z20.string().optional().nullable(),
-  endereco_cep: z20.string().optional().nullable(),
-  endereco_pontoreferencia: z20.string().optional().nullable(),
-  endereco_ll: z20.string().optional().nullable()
+  contrato_unificado_principal: z21.number().optional().nullable(),
+  contrato_unificado_filhos: z21.array(z21.number()).optional().nullable(),
+  tags: z21.array(tagSchema).optional().nullable(),
+  anotacoes: z21.array(z21.object({})).optional().nullable(),
+  contratoCentralLogin: z21.string().optional().nullable(),
+  contratoCentralSenha: z21.string().optional().nullable(),
+  servico_login: z21.string().optional().nullable(),
+  servico_senha: z21.string().optional().nullable(),
+  servico_plano: z21.string().optional().nullable(),
+  servico_grupo: z21.string().optional().nullable(),
+  servico_tipo_conexao: z21.string().optional().nullable(),
+  servico_vlan: z21.string().optional().nullable(),
+  servico_mac: z21.string().optional().nullable(),
+  servico_mac2: z21.string().optional().nullable(),
+  servico_wifi_ssid: z21.string().optional().nullable(),
+  servico_wifi_ssid_5: z21.string().optional().nullable(),
+  servico_wifi_password: z21.string().optional().nullable(),
+  servico_wifi_password_5: z21.string().optional().nullable(),
+  servico_wifi_channel: z21.string().optional().nullable(),
+  servico_wifi_channel_5: z21.string().optional().nullable(),
+  razaoSocial: z21.string().optional().nullable(),
+  cpfCnpj: z21.string().optional().nullable(),
+  dataNascimento: z21.string().optional().nullable(),
+  telefones: z21.array(contactEntrySchema).optional().nullable(),
+  telefones_cargos: z21.array(z21.object({})).optional().nullable(),
+  emails: z21.array(contactEntrySchema).optional().nullable(),
+  outros: z21.array(z21.object({})).optional().nullable(),
+  endereco_logradouro: z21.string().optional().nullable(),
+  endereco_numero: z21.number().optional().nullable(),
+  endereco_complemento: z21.string().optional().nullable(),
+  endereco_bairro: z21.string().optional().nullable(),
+  endereco_cidade: z21.string().optional().nullable(),
+  endereco_uf: z21.string().optional().nullable(),
+  endereco_cep: z21.string().optional().nullable(),
+  endereco_pontoreferencia: z21.string().optional().nullable(),
+  endereco_ll: z21.string().optional().nullable()
 });
-var lookupCustomerSchema = z20.object({
-  msg: z20.string().optional().nullable(),
-  contratos: z20.array(customerContractSchema)
+var lookupCustomerSchema = z21.object({
+  msg: z21.string().optional().nullable(),
+  contratos: z21.array(customerContractSchema)
 });
 var lookupCustomerKeyFields = [
   "contratos",
@@ -1175,15 +1245,15 @@ var lookupCustomerDefinition = {
 };
 
 // src/endpoints/ura/open-ticket.ts
-import { z as z21 } from "zod";
-var openTicketSchema = z21.object({
-  status: z21.literal(1),
-  protocolo: z21.string(),
-  id: z21.number(),
-  contratoId: z21.number().optional().nullable(),
-  razaoSocial: z21.string().optional().nullable(),
-  cpfCnpj: z21.string().optional().nullable(),
-  msg: z21.string().optional().nullable()
+import { z as z22 } from "zod";
+var openTicketSchema = z22.object({
+  status: z22.literal(1),
+  protocolo: z22.string(),
+  id: z22.number(),
+  contratoId: z22.number().optional().nullable(),
+  razaoSocial: z22.string().optional().nullable(),
+  cpfCnpj: z22.string().optional().nullable(),
+  msg: z22.string().optional().nullable()
 });
 var openTicketKeyFields = ["status", "protocolo", "id"];
 var ticketOpenedItemPath = "";
@@ -1203,6 +1273,7 @@ var openTicketDefinition = {
 // src/client.ts
 var createSgpClient = (config) => ({
   ura: {
+    listAnnotations: (params) => listAnnotations(config, params),
     listClients: (params) => callEndpoint(config, listClientsDefinition, { ...params }),
     lookupCustomer: (params) => callEndpoint(config, lookupCustomerDefinition, { ...params }),
     listContracts: (params) => callEndpoint(config, listContractsDefinition, { ...params }),
@@ -1325,6 +1396,8 @@ export {
   listContractsDefinition,
   listClientsKeyFields,
   listClientsDefinition,
+  listAnnotationsSchema,
+  listAnnotationsKeyFields,
   invoiceSecretKeys,
   invoicePersonalKeys,
   invoiceItemPath,
@@ -1368,6 +1441,9 @@ export {
   clientItemPath,
   checkCoverageKeyFields,
   checkCoverageDefinition,
+  annotationSecretKeys,
+  annotationPersonalKeys,
+  annotationItemPath,
   addCustomerDocumentKeyFields,
   addCustomerDocumentDefinition
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sgp-sdk",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Unofficial TypeScript client for the SGP (TSMX) ISP ERP HTTP API, with normalized errors and explicit write outcomes. Not affiliated with TSMX.",
   "license": "MIT",
   "type": "module",