@financial-times/cp-content-pipeline-client 3.3.6 → 3.3.7

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 (13) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +86 -68
  3. package/lib/client-version.d.ts +1 -1
  4. package/lib/client-version.js +1 -1
  5. package/lib/generated/index.d.ts +546 -2
  6. package/lib/generated/index.js.map +1 -1
  7. package/lib/schema-version.d.ts +1 -1
  8. package/lib/schema-version.js +1 -1
  9. package/package.json +2 -2
  10. package/src/client-version.ts +1 -1
  11. package/src/generated/index.ts +546 -2
  12. package/src/schema-version.ts +1 -1
  13. package/tsconfig.tsbuildinfo +1 -1
package/CHANGELOG.md CHANGED
@@ -426,6 +426,12 @@
426
426
  * devDependencies
427
427
  * @financial-times/cp-content-pipeline-schema bumped from ^2.5.2 to ^2.5.3
428
428
 
429
+ ### Dependencies
430
+
431
+ * The following workspace dependencies were updated
432
+ * devDependencies
433
+ * @financial-times/cp-content-pipeline-schema bumped from ^2.5.3 to ^2.5.4
434
+
429
435
  ## [3.3.1](https://github.com/Financial-Times/cp-content-pipeline/compare/cp-content-pipeline-client-v3.3.0...cp-content-pipeline-client-v3.3.1) (2024-03-22)
430
436
 
431
437
 
package/README.md CHANGED
@@ -1,83 +1,111 @@
1
- # Content Pipeline GraphQL Client
1
+ # Content Pipeline Client
2
2
 
3
- Provides a JS client for querying the GraphQL API, with a pre-defined query for a complete article, along with type definitions to use in components.
3
+ A JavaScript client for querying the GraphQL API.
4
+
5
+ It exports:
6
+
7
+ - The generated TypeScript type definitions for `cp-content-pipeline-ui`, which are the output of [@graphql-codegen](https://www.npmjs.com/package/@graphql-codegen/cli) on `typeDefs` defined in `cp-content-pipeline-schema`.
8
+ - A pre-defined query for a complete article written in `cp-content-pipeline-schema`.
9
+
10
+ ## Table of Contents
11
+
12
+ - [Getting Started](#getting-started)
13
+ - [Versioning](#versioning)
14
+ - [Overview](#overview)
4
15
 
5
- The published `cp-content-pipeline-client` package mainly consists of generated code. To understand more about how this package is produced read the ["How this package is produced"](#how-this-package-is-produced) section below
6
16
 
7
17
  ## Getting Started
8
18
 
9
- Run `npm install` then `npm start` from [the monorepo project root](../../README.md#commands).
19
+ To run the client, see [Quick Start](../../README.md#quick-start).
10
20
 
11
- The project has its own playground ui at the url it's running on.
21
+ ### Usage
12
22
 
13
- ## Using the Client
23
+ #### Initialising the client
14
24
 
15
25
  ```js
16
26
  import initContentPipelineClient from '@financial-times/cp-content-pipeline-client'
27
+ import { Body } from '@financial-times/cp-content-pipeline-ui'
17
28
 
29
+ // initialise the content pipeline client
18
30
  const client = initContentPipelineClient({
19
31
  apiKey: 'some-secret',
20
- baseUrl: 'http://localhost:3001', // for testing purposes only
21
- systemCode: 'cp-content-pipeline', // your consuming app's Biz Ops system code
22
- timeout: 2000, // default = 1 minute
32
+ systemCode: 'app-name',
33
+ })
34
+ ```
35
+
36
+ #### Calling the client
37
+
38
+ You can either query the client by using the main `.Article` method:
39
+
40
+ ```js
41
+ // query the client instance, passing in a `uuid` parameter
42
+ const { content } = await client.Article({
43
+ uuid: 'a70c927-ff16-4977-942f-897cfd1349af',
23
44
  })
45
+ ```
46
+
47
+ Or by using the `.ArticleCannedQuery` method, which uses the canned query `GET` endpoint:
24
48
 
25
- const { content: articleData } = await client.Article({
26
- uuid: request.params.uuid,
27
- useVanities: true,
49
+ ```js
50
+ // query the client instance, passing in a `uuid` parameter
51
+ const { content } = await client.ArticleCannedQuery({
52
+ uuid: 'a70c927-ff16-4977-942f-897cfd1349af',
28
53
  })
29
54
  ```
30
55
 
31
- ### URLs and versioning
56
+ ```js
57
+ // render JSX component with the fetched content
58
+ const ArticleBody = () => {
59
+ return (
60
+ ...
61
+ <Body content={content} />
62
+ )
63
+ }
64
+ ```
32
65
 
33
- The client requests versions of the API based on the version of the schema it has installed as a dependency. For example, a client that depends on `@financial-times/cp-content-pipeline-schema` 0.7.x will send requests to `https://www.ft.com/__content/v0.7`.
66
+ ## Versioning
34
67
 
35
- When we release a new major version of the schema, we'll release a new major version of the client alongside it, so consuming apps can install the new version of the client to get the breaking schema changes, and consumers still depending on the old client version will get the old schema.
68
+ The client requests versions of the API based on the version of the schema it has installed as a dependency. For example, a client that depends on
69
+
70
+ ```
71
+ @financial-times/cp-content-pipeline-schema: "2.0.x"
72
+ ```
36
73
 
37
- The `baseUrl` option overrides this logic, and forces all requests to go to that URL, without the version suffix. This means if you're overriding `baseUrl`, you're opting out of having the client handle versioning for you. For this reason, **`baseUrl` should only be used for testing purposes**, e.g. to force the client to send requests to a locally-running API.
74
+ will send requests to `https://www.ft.com/__content/v2`.
38
75
 
39
- ## How this package is produced
76
+ When we release a new major version of the schema, we'll release a new major version of the client alongside it, so consuming apps can install the new version of the client to get the breaking schema changes, and consumers still depending on the old client version will get the old schema.
40
77
 
41
- The published `cp-content-pipeline-client` package mainly consists of generated code which is the output of [@graphql-codegen](https://www.npmjs.com/package/@graphql-codegen/cli).
78
+ The `baseUrl` option overrides this logic:
42
79
 
43
- ### What is used to generate the GraphQL client
80
+ ```js
81
+ const client = initContentPipelineClient({
82
+ apiKey: 'some-secret',
83
+ systemCode: 'app-name'
84
+ baseUrl: 'https://ft.com/__content/v3'
85
+ });
86
+ ```
44
87
 
45
- The generated GraphQL client is produced using the output of the `cp-content-pipeline-schema` package, along with the hand-written queries within the `./queries` directory of the client package.
88
+ It forces all requests to go to that URL. If the version is not included, it will default to the latest schema version.
46
89
 
47
- ### What is used to generate the TypeScript type definitions
90
+ This means if you're overriding `baseUrl`, you're **opting out** of having the client handle versioning for you. For this reason, **`baseUrl` should only be used for testing purposes**, e.g. to force the client to send requests to a locally-running API.
48
91
 
49
- The `cp-content-pipeline-client` also exposes TypeScript type definitions. These type definitions are generated using the GraphQL typeDef's for article features within the `cp-content-pipeline-schema` package.
92
+ ### Overview
50
93
 
51
- ### Code generation diagram
94
+ This diagram visualises how various parts piece together to produce the published `cp-content-pipeline-client`:
52
95
 
53
- This diagram visualises how these parts piece together to produce the published `cp-content-pipeline-client`:
54
96
 
55
97
  ```mermaid
56
98
  flowchart TB
57
99
 
58
100
  subgraph cpContentPipelineSchema[cp-content-pipeline-schema]
59
- subgraph articleFeatures[Article features]
60
- id1[Schema, Resolvers & Typedefs for each article feature <br> Article features are things like toppers, teasters, links, pullquotes, etc]:::description
101
+ subgraph typeDefs[typeDefs, resolvers, articleDocumentQuery]
61
102
  end
62
- articleFeatures:::internalComponent
103
+ typeDefs:::internalComponent
63
104
  end
64
- cpContentPipelineSchema:::internalContainer
65
105
 
66
106
  subgraph cpContentPipelineClient[cp-content-pipeline-client]
67
- subgraph codegenConfig[Codegen config]
68
- id2[A codegen config file]:::description
69
- end
70
- codegenConfig:::internalComponent
71
- subgraph articleQuery[Article GraphQL Query]
72
- id3[A article.graphql file is a hand crafted query for a complete article]:::description
73
- end
74
- articleQuery:::internalComponent
75
-
76
-
77
107
  subgraph toolkitPlugin[Codegen Toolkit Plugin]
78
- id4[A toolkit plugin wrapper around graphql-codegen.<br>Triggered by commands such as npm start]:::description
79
- subgraph codegenPackage[graphql-codegen package]
80
- id5[A third party package that takes GraphQL schemas to produce a variety of outputs]:::description
108
+ subgraph codegenPackage[graphql-codegen third party package]
81
109
  end
82
110
  codegenPackage:::externalSystem
83
111
 
@@ -85,52 +113,42 @@ subgraph cpContentPipelineClient[cp-content-pipeline-client]
85
113
  toolkitPlugin:::internalComponent
86
114
 
87
115
 
88
- subgraph generatedOuput[Generate Output]
89
- id6[The generated output of the codegen toolkit plugin<br>The generated output is what gets used when the package is published]:::description
116
+ subgraph generatedOuput[Generated Output]
117
+ id0[Published exports]:::description
90
118
  subgraph graphqlClient[GraphQL Client]
91
- id7[A client for querying the GraphQL API]:::description
92
119
  end
93
120
  graphqlClient:::internalComponent
94
121
  subgraph tsTypes[Typescript Types]
95
- id8[TypeScript types generated from the GraphQL schema]:::description
96
122
  end
97
123
  tsTypes:::internalComponent
98
124
  end
99
125
  generatedOuput:::internalGrouping
100
126
  end
101
- cpContentPipelineClient:::internalContainer
102
127
 
103
- subgraph key[Key]
104
- subgraph keyPackage[cp-content-pipeline package]
105
- id9[A package from the cp-content-pipeline monorepo]:::description
106
- end
107
- keyPackage:::internalContainer
108
128
 
109
- subgraph keyComponent[Package Component]
110
- id10[A component within a cp-content-pipeline package]:::description
111
- end
112
- keyComponent:::internalComponent
129
+ class cpContentPipelineSchema cpContentPipelineSchema
113
130
 
114
- subgraph keyExternal[External Component]
115
- id11[An external package/component/dependency]:::description
116
- end
117
- keyExternal:::externalSystem
118
- end
119
- key:::keyContainer
120
131
 
121
- codegenConfig-->codegenPackage
122
- articleQuery--Codegen uses the article query to generate the client-->codegenPackage
123
- codegenPackage--Produces the API client-->graphqlClient
124
- codegenPackage--Produces the TypeScript types---->tsTypes
125
- articleFeatures--Codegen uses the Schema package to generate the client <br> The typedefs are also used to generate TypeScript Types-->codegenPackage
132
+ codegenPackage--Outputs-->graphqlClient
133
+ codegenPackage--Outputs---->tsTypes
134
+ cpContentPipelineSchema-->toolkitPlugin
126
135
 
127
136
  classDef internalContainer fill:#D4DFE8,stroke-width:0px
128
137
  classDef internalComponent fill:#BDA8FA,stroke-width:0px
129
138
  classDef internalGrouping stroke-width:2px,fill:none,stroke:black
130
139
  classDef externalSystem fill:#03A696,stroke-width:1px,stroke:black
131
140
  classDef description stroke-width:0px,color:#000,fill:transparent,font-size:13px
132
- classDef keyContainer fill: transparent, stroke: black,
141
+ classDef keyContainer fill: transparent, stroke: black
142
+
143
+ %% Styling
144
+ classDef cpContentPipelineClient margin-right:10.5cm
145
+ class cpContentPipelineClient cpContentPipelineClient
146
+
147
+ classDef cpContentPipelineSchema margin-right:3.5cm
148
+
149
+ classDef generatedOuput margin-right:8.7cm
150
+ class generatedOuput generatedOuput
133
151
 
134
152
  style generatedOuput stroke-dasharray: 5 5
135
153
 
136
- ```
154
+ ```
package/lib/client-version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const version = "3.3.6";
1
+ export declare const version = "3.3.7";
package/lib/client-version.js CHANGED
@@ -2,5 +2,5 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.version = void 0;
4
4
  // Generated by genversion.
5
- exports.version = '3.3.6';
5
+ exports.version = '3.3.7';
6
6
  //# sourceMappingURL=client-version.js.map