{"_id":"@antunes_s/clasp-types","name":"@antunes_s/clasp-types","dist-tags":{"latest":"2.0.0"},"versions":{"2.0.0":{"name":"@antunes_s/clasp-types","version":"2.0.0","type":"module","description":"Generate d.ts from Google Apps Script clasp projects (TypeDoc 0.28 compatible)","homepage":"https://github.com/antune-ss/clasp-types#readme","main":"./dist/index.js","bin":{"clasp-types":"dist/index.js"},"author":{"name":"Gustavo Antunes"},"contributors":[{"name":"Mael Caldas","url":"https://github.com/maelcaldas"}],"repository":{"type":"git","url":"git+https://github.com/antune-ss/clasp-types.git"},"license":"MIT","scripts":{"clean":"rimraf dist","prebuild":"copyfiles ./src/lib/builders/*.json -f dist/lib/builders/","build":"tsc -p .","dev":"yarn build -w","test":"bun test","patch":"yarn version --patch","minor":"yarn version --minor","major":"yarn version --major","preversion":"yarn build","postversion":"git push && git push --tags && yarn publish --access public --new-version $npm_package_version && echo \"Successfully released version $npm_package_version!\""},"devDependencies":{"@types/fs-extra":"^11.0.4","@types/node":"^26.2.0","copyfiles":"^2.4.1","nodemon":"^3.1.14","rimraf":"^6.1.3","ts-node":"^10.9.2","typescript":"^5.9.3"},"dependencies":{"commander":"^15.0.0","fs-extra":"^11.4.0","typedoc":"^0.28.20"},"keywords":["google-apps-script","typescript","clasp","sdk"],"gitHead":"6ef9fc62652a7f10cd573a4fdb15935bd204386f","_id":"@antunes_s/clasp-types@2.0.0","bugs":{"url":"https://github.com/antune-ss/clasp-types/issues"},"_nodeVersion":"24.11.1","_npmVersion":"11.18.0","dist":{"integrity":"sha512-pZzu56BCRSG2L8WP2jXm93XAb5wTuOLJcjshn4PRrfhCR+kUoPxgFCA1WrWP1b1Vu+0g/rDsX2mNk/OsIIbuCg==","shasum":"bf49ab546a92eaa57c99bc6d10f503886b28e87f","tarball":"https://registry.npmjs.org/@antunes_s/clasp-types/-/clasp-types-2.0.0.tgz","fileCount":32,"unpackedSize":225766,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDRaEsA/PVhXlalyqk1KOKTGI2OCgIWSCcTl+myKPBLmAiEAqJFn2I9zlQfz75RC4BQnm+e5aEUIlrUCr4+g5u0idhs="}]},"_npmUser":{"name":"antunes_s","email":"guantunes567@gmail.com"},"directories":{},"maintainers":[{"name":"antunes_s","email":"guantunes567@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/clasp-types_2.0.0_1788367166282_0.6679901141541251"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T16:39:26.109Z","2.0.0":"2026-09-02T16:39:26.466Z","modified":"2026-09-02T16:39:26.719Z"},"maintainers":[{"name":"antunes_s","email":"guantunes567@gmail.com"}],"description":"Generate d.ts from Google Apps Script clasp projects (TypeDoc 0.28 compatible)","homepage":"https://github.com/antune-ss/clasp-types#readme","keywords":["google-apps-script","typescript","clasp","sdk"],"repository":{"type":"git","url":"git+https://github.com/antune-ss/clasp-types.git"},"contributors":[{"name":"Mael Caldas","url":"https://github.com/maelcaldas"}],"author":{"name":"Gustavo Antunes"},"bugs":{"url":"https://github.com/antune-ss/clasp-types/issues"},"license":"MIT","readme":"[BkperApp]: https://github.com/bkper/bkper-app\r\n[API Extractor]: https://api-extractor.com/\r\n[grant]: https://github.com/grant/google-apps-script-dts\r\n[motemen]: https://github.com/motemen/dts-google-apps-script\r\n[mtgto]: https://github.com/mtgto/dts-google-apps-script-advanced\r\n[Add-on for Google Sheets]: https://workspace.google.com/marketplace/app/bkper/360398463400s\r\n[HTML Service]: https://developers.google.com/apps-script/guides/html/communication\r\n[Bibliotecas]: https://developers.google.com/apps-script/guides/libraries\r\n[library]: https://developers.google.com/apps-script/guides/libraries\r\n[Client-side API]: https://developers.google.com/apps-script/guides/html/reference/run\r\n[clasp]: https://github.com/google/clasp\r\n[TypeScript]: https://github.com/google/clasp/blob/master/docs/typescript.md\r\n[inline-source-cli]: https://www.npmjs.com/package/inline-source-cli\r\n[glob-exec]: https://www.npmjs.com/package/glob-exec\r\n[DefinitelyTyped]: http://definitelytyped.org/\r\n[example]: https://www.npmjs.com/package/@bkper/bkper-app-types\r\n\r\n# clasp-types\r\n\r\n[![npm](https://img.shields.io/npm/v/clasp-types)](https://www.npmjs.com/package/clasp-types)\r\n\r\nEsse é um gerador de definições [TypeScript] para permitir que os projetos [clasp] realizem o **autocomplete** e a **verificação de tipos** para as suas [Bibliotecas] e [Client-side API]'s Orientadas a Objetos do Google Apps Script.\r\n\r\n*Biblioteca:*\r\n![library-autocomplete](https://raw.githubusercontent.com/bkper/clasp-types/master/imgs/library-autocomplete.png)\r\n\r\n*Client-side API:*\r\n![client-side-api-autocomplete](https://raw.githubusercontent.com/bkper/clasp-types/master/imgs/client-side-api-autocomplete.png)\r\n\r\nEle funciona como o [API Extractor], lendo os comentários ```@public``` em qualquer function, class, interface, variável ou enum que você deseje expor, e gerando os arquivos d.ts consistentemente.\r\n\r\n## Funcionalidades\r\n\r\n- **d.ts rollup:** Gera um único arquivo `d.ts` a partir de todos os seus arquivos `.ts`, encapsulando as funções globais dentro da interface da sua Biblioteca.\r\n\r\n- **API limpa da biblioteca:** Expõe apenas funções, variáveis e métodos marcados com a anotação `@public`, construindo uma interface mais limpa e evitando o uso de elementos que não foram feitos para serem expostos.\r\n\r\n- **Pronto para publicar:** Gera um pacote npm com instruções claras de configuração, pronto para ser publicado.\r\n\r\n- **Client-side API:** Para Add-ons e Web Apps, gera as tipagens das suas funções globais expostas com `@public` num único arquivo `d.ts` (na pasta `@types`), permitindo que você tenha o *autocomplete* da API do servidor diretamente no código do cliente (front-end).\r\n\r\nAqui está um [exemplo] de tipagens de biblioteca criadas e publicadas com o clasp-types.\r\n\r\n> Nota: O clasp-types foi desenvolvido para gerar os arquivos `d.ts` a partir do seu próprio código Apps Script que já está escrito em TypeScript. Para baixar as tipagens dos serviços nativos e avançados do Google Apps Script (como o `SpreadsheetApp`), veja https://github.com/grant/google-apps-script-dts\r\n\r\n## Instalação\r\n\r\n```\r\nnpm i -S clasp-types\r\n```\r\nou\r\n```\r\nyarn add --dev clasp-types\r\n```\r\n\r\n## Comando\r\n\r\n```\r\nclasp-types\r\n```\r\n\r\nParâmetros opcionais:\r\n```sh\r\n--src          <folder>    # default: ./src     - Pasta fonte dos aquivos .ts\r\n--out          <folder>    # default: ./dist    - Pasta de saída para o arquivo .d.ts            \r\n--client                   # default: false     - Parâmetro para gerar uma Client-side API\r\n--root         <folder>    # default: ./        - Pasta raiz do projeto \r\n```\r\n\r\n## Configuração da Biblioteca\r\n\r\n### 1) Adicione o *namespace* e o *name* da sua biblioteca no ```.clasp.json```, eles devem ser diferentes:\r\n```json\r\n{\r\n  \"scriptId\": \"1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF\",\r\n  \"rootDir\": \"./src\",\r\n  \"library\": {\r\n    \"namespace\": \"gsuitedevs\",\r\n    \"name\": \"OAuth2\"\r\n  }\r\n}\r\n```\r\n\r\n### 2) Adicione a anotação ```@public``` nos comentários do código que você deseja expor:\r\n\r\n```ts\r\n/**\r\n * Cria um serviço\r\n * \r\n * @public\r\n */\r\nfunction createService(serviceName: string) {\r\n  return new Service(serviceName);\r\n}\r\n\r\n/**\r\n * O serviço OAuth\r\n * \r\n * @public\r\n */\r\nclass Service {\r\n  name: string;\r\n  params_: any;\r\n  constructor(name: string) {\r\n    this.name = name;;\r\n  }\r\n\r\n  public getName() {\r\n    return this.name;\r\n  }\r\n  \r\n\r\n  /**\r\n   * Define um parâmetro adicional a ser usado ao construir a URL de autorização.\r\n   */\r\n  public setParam(name: string, value: string): Service {\r\n    this.params_[name] = value;\r\n    return this;\r\n  };\r\n\r\n}\r\n```\r\n\r\n### Rode o ```clasp-types``` para gerar um **pacote npm** com um index.d.ts parecido com este:\r\n\r\n```ts\r\ndeclare namespace gsuitedevs {\r\n\r\n    /**\r\n     * O ponto de entrada principal para interagir com OAuth2\r\n     *\r\n     * Script ID: **1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF**\r\n     */\r\n    export interface OAuth2 {\r\n\r\n        /**\r\n         * Cria um serviço\r\n         */\r\n        createService(serviceName: string): Service;\r\n\r\n    }\r\n\r\n    /**\r\n     * O serviço OAuth\r\n     */\r\n    export interface Service {\r\n\r\n        getName(): string;\r\n\r\n        /**\r\n         * Define um parâmetro adicional a ser usado ao construir a URL de autorização.\r\n         */\r\n        setParam(name: string, value: string): Service;\r\n\r\n    }\r\n\r\n}\r\n\r\ndeclare var OAuth2: gsuitedevs.OAuth2;\r\n```\r\n\r\n> *Notas:* \r\n> - Nas classes anotadas com ```@public```, os métodos dentro dela também devem ser marcados explicitamente como ```public``` para serem exportados. Métodos marcados como **Private** ou **protected** **não** serão expost. \r\n> - Interfaces e Enumerações com a anotação ```@public``` terão todos os seus membros expostos por padrão.\r\n\r\nUm **pacote npm pronto para ser publicado** será gerado na pasta de saída (output folder), com algumas instruções de instalação no ```README.md```, assim você pode compartilhar facilmente as tipagens da sua biblioteca. Aqui está um [exemplo].\r\n\r\n> Sugestão: Você pode adicionar uma [dist-tag](https://docs.npmjs.com/cli/dist-tag) na distribuição do seu pacote de tipos que seja igual à [version](https://developers.google.com/apps-script/guides/versions) do seu script lá no Google, por exemplo, ```v23```. Assim os usuários conseguem linkar a versão das tipagens com a versão do script, e usar aquela que for correspondente.\r\n\r\n### Dependências\r\n\r\nSe o seu pacote expor uma dependência transitiva nos tipos dos seus **parâmetros (params)** ou de **retorno (return)**, como por exemplo usar o `GoogleAppsScript.HTML.HtmlOutput` vindo do pacote `@types/google-apps-script`, adicione esse pacote na seção **\"dependencies\"** do seu `package.json`, em vez de colocar em \"devDependencies\":\r\n\r\n```json\r\n  \"dependencies\": {\r\n    \"@types/google-apps-script\": \"^0.0.59\"\r\n  }\r\n```\r\nDessa forma, o ```clasp-types``` vai configurar corretamente a referência (reference tag) lá no topo do seu ```index.d.ts```:\r\n\r\n```ts\r\n/// <reference types=\"google-apps-script\" />\r\n```\r\n\r\nE no ```package.json``` resultante da compilação, ele ficará assim:\r\n\r\n```json\r\n  \"dependencies\": {\r\n    \"@types/google-apps-script\": \"*\"\r\n  },\r\n```\r\n\r\n## Configuração da Client-side API\r\n\r\n### 1) Adicione a anotação ```@public``` no código que você deseja expor ao cliente\r\n```ts\r\n/**\r\n * Executa uma soma no lado do servidor, a partir do lado do cliente.\r\n * \r\n * @public\r\n */\r\nfunction sumOnServer(a: number, b: number): number {\r\n  return a + b;\r\n}\r\n```\r\n\r\n### 2) Rode ```clasp-types --client``` para gerar um index.d.ts como esse:\r\n\r\n```ts\r\ndeclare namespace google {\r\n\r\n    namespace script {\r\n\r\n        export interface Runner {\r\n\r\n            withSuccessHandler(handler: Function): Runner;\r\n\r\n            withFailureHandler(handler: (error: Error) => void): Runner;\r\n\r\n            withUserObject(object: any): Runner;\r\n\r\n            sumOnServer(a: number, b: number): void //number;\r\n            ...\r\n\r\n        }\r\n\r\n        export var run: Runner;\r\n\r\n    }\r\n    ...\r\n\r\n}\r\n```\r\n\r\n### TypeScript on Client-side\r\n\r\nPara desenvolver com [TypeScript] no lado do cliente (client-side), você deve trabalhar com arquivos `ts` separados e embutir (inline) o `js` correspondente, bem como todo o seu `css` na mesma página, a fim de que o template HTML resultante possa ser processado corretamente pelo [HTML Service].\r\n\r\nPara realizar essa inserção de código (inlining), uma ótima ferramenta é o [inline-source-cli], através do qual você pode simplesmente adicionar uma tag `inline` nas suas referências de `js` e `css`:\r\n\r\n```html\r\n<head>\r\n  ...\r\n  <link inline href=\"page-style.css\" rel=\"stylesheet\">\r\n</head>\r\n<body>\r\n  ...\r\n  <script inline src=\"page-activity.js\"></script>\r\n  <script inline src=\"page-view.js\"></script>\r\n</body>\r\n```\r\n\r\nE então usar uma ferramenta como o [glob-exec] para embutir (inline) todos os seus códigos-fonte usando uma única linha de comando:\r\n\r\n```sh\r\nglob-exec --foreach './build/**/*.html' --  'cat {{file}} | inline-source --root build > dist/{{file.name}}{{file.ext}}'\r\n```\r\n\r\n## Background\r\n\r\nDont know yet\r\n\r\n## Toda ajuda é bem-vinda (Contribuindo)\r\n- Identificar casos extremos (*edge cases*) para parâmetros e tipos de retorno.\r\n\r\n- Gerar arquivos `d.ts` a partir de uma biblioteca `js` bem documentada, para que a ferramenta também possa funcionar com bibliotecas como a [OAuth2](https://github.com/gsuitedevs/apps-script-oauth2).\r\n\r\n- Gerar arquivos `ts` de cliente ([como este](https://github.com/google/apis-client-generator)) e `d.ts` a partir de especificações [openapi](https://swagger.io/specification/) e [API Discovery](https://developers.google.com/discovery/), para bibliotecas nos mesmos moldes dos [Serviços Avançados](https://developers.google.com/apps-script/guides/services/advanced).\r\n\r\n## Créditos\r\n\r\nEste projeto é um *fork* compatível com o TypeDoc 0.28 do repositório original [clasp-types](https://github.com/bkper/clasp-types), criado por [Mael Caldas](https://github.com/maelcaldas).","readmeFilename":"README.pt-br.md","_rev":"1-aaa125c88604dbb6d61febb5f1047513"}