Debian Codegraph @

srht/metasrht/schema.graphqls

raw
1 # This schema definition is available in the public domain, or under the terms
2 # of CC-0, at your choice.
3
4 scalar Cursor
5
6 "String of the format %Y-%m-%dT%H:%M:%SZ"
7 scalar Time
8
9 """
10 A file uploaded alongside the GraphQL request. This API is compatible with the
11 multipart request specification for requests that include uploads:
12
13 https://github.com/jaydenseric/graphql-multipart-request-spec
14 """
15 scalar Upload
16
17 """
18 URL from which some secondary data may be retrieved.
19
20 Resources which are access protected require you to provide a valid
21 Authentication header when retrieving this URL. URLs are not guaranteed to be
22 consistent for an extended length of time; applications should submit a new
23 GraphQL request each time they wish to access the data at the provided URL.
24 """
25 scalar URL
26
27 "ISO-3166 country code"
28 scalar Country
29
30 """
31 This is used to decorate fields which are only accessible with a personal
32 access token, and are not available to clients using OAuth 2.0 access tokens.
33 """
34 directive @private on FIELD_DEFINITION
35
36 """
37 Used to decorate fields which are for internal use, and are not available to
38 normal API users.
39 """
40 directive @internal on FIELD_DEFINITION
41
42 """
43 Used to decorate fields which are for internal use, and are not available to
44 normal API users.
45 """
46 directive @anoninternal on FIELD_DEFINITION
47
48 """
49 Used to decorate fields which are only available to admin accounts.
50 """
51 directive @admin on FIELD_DEFINITION
52
53 """
54 Used to provide a human-friendly description of an access scope.
55 """
56 directive @scopehelp(details: String!) on ENUM_VALUE
57
58 enum AccessScope {
59 AUDIT_LOG @scopehelp(details: "audit log")
60 BILLING @scopehelp(details: "billing history")
61 PGP_KEYS @scopehelp(details: "PGP keys")
62 SSH_KEYS @scopehelp(details: "SSH keys")
63 PROFILE @scopehelp(details: "profile information")
64 }
65
66 enum AccessKind {
67 RO @scopehelp(details: "read")
68 RW @scopehelp(details: "read and write")
69 }
70
71 """
72 Decorates fields for which access requires a particular OAuth 2.0 scope with
73 read or write access. For the meta.sr.ht API, you have access to all public
74 information without any special permissions - user profile information,
75 public keys, and so on.
76 """
77 directive @access(scope: AccessScope!, kind: AccessKind!) on FIELD_DEFINITION
78
79 # https://semver.org
80 type Version {
81 major: Int!
82 minor: Int!
83 patch: Int!
84 buildVersion: String!
85 buildDate: String!
86
87 """
88 If this API version is scheduled for deprecation, this is the date on which
89 it will stop working; or null if this API version is not scheduled for
90 deprecation.
91 """
92 deprecationDate: Time
93
94 "Optional features"
95 features: Features!
96 }
97
98 "Describes available optional features"
99 type Features {
100 avatars: Boolean!
101 }
102
103 interface Entity {
104 id: Int!
105 created: Time!
106 updated: Time!
107 """
108 The canonical name of this entity. For users, this is their username
109 prefixed with '~'. Additional entity types will be supported in the future.
110 """
111 canonicalName: String!
112 }
113
114 enum UserType {
115 PENDING
116 USER
117 ADMIN
118 SUSPENDED
119 }
120
121 enum PaymentStatus {
122 "User does not pay for their account"
123 UNPAID
124 "User is paid and their payment is current"
125 CURRENT
126 "User's payment has lapsed"
127 DELINQUENT
128 "User's paid services are subsidized"
129 SUBSIDIZED
130 "User receives paid services for free"
131 FREE
132 }
133
134 type User implements Entity {
135 id: Int!
136 created: Time!
137 updated: Time!
138 canonicalName: String!
139 username: String!
140 email: String!
141 url: String
142 location: String
143 bio: String
144 avatar: URL
145 pronouns: String
146 userType: UserType!
147
148 sshKeys(cursor: Cursor): SSHKeyCursor! @access(scope: SSH_KEYS, kind: RO)
149 pgpKeys(cursor: Cursor): PGPKeyCursor! @access(scope: PGP_KEYS, kind: RO)
150
151 """
152 User's current payment status. Only available if authenticated as this user.
153 """
154 paymentStatus: PaymentStatus! @access(scope: BILLING, kind: RO)
155
156 """
157 Date at which next payment is due. Only available if authenticated as this
158 user.
159 """
160 paymentDue: Time @access(scope: BILLING, kind: RO)
161
162 """
163 Details about the user's current paid subscription. Only available if
164 authenticated as this user.
165 """
166 subscription: BillingSubscription @access(scope: BILLING, kind: RO)
167
168 """
169 Returns invoices for this user. Only available if authenticated as this user.
170 """
171 invoices(cursor: Cursor): InvoiceCursor! @access(scope: BILLING, kind: RO)
172
173 """
174 User's billing address, if applicable, for invoicing.
175 """
176 billingAddress: BillingAddress @access(scope: BILLING, kind: RO)
177
178 """
179 User's payment methods, if any.
180 """
181 paymentMethods: [PaymentMethod!]! @access(scope: BILLING, kind: RO)
182
183 """
184 The default payment method in use for automatic subscription renewals.
185 """
186 defaultPaymentMethod: PaymentMethod
187
188 ### ###
189 ### Internal user attributes ###
190 ### ###
191
192 "Returns true if this user should have access to paid services."
193 receivesPaidServices: Boolean! @private
194
195 "Notice to provide to a suspended account"
196 suspensionNotice: String @anoninternal
197 }
198
199 type AuditLogEntry {
200 id: Int!
201 created: Time!
202 ipAddress: String!
203 eventType: String!
204 details: String
205 }
206
207 type LoginSecurity {
208 "True if TOTP (time-based one time passwords) is enabled for 2FA"
209 totp: Boolean!
210 }
211
212 """
213 An SSH public key associated with an account.
214 """
215 type SSHKey {
216 id: Int!
217 rid: ID!
218 created: Time!
219 lastUsed: Time
220 user: User! @access(scope: PROFILE, kind: RO)
221 "The raw input as provided by the user, see the `createSSHKey` mutation."
222 key: String!
223 "The legacy MD5 fingerprint of the key."
224 fingerprint: String!
225 comment: String
226 }
227
228 type PGPKey {
229 id: Int!
230 rid: ID!
231 created: Time!
232 user: User! @access(scope: PROFILE, kind: RO)
233 key: String!
234 fingerprint: String!
235 }
236
237 enum Currency {
238 EUR
239 USD
240 }
241
242 enum PaymentInterval {
243 MONTHLY
244 ANNUALLY
245 }
246
247 """
248 A paid product available for purchase.
249 """
250 type Product {
251 id: Int!
252 name: String!
253 prices: [ProductPrice!]!
254
255 """
256 This product has been retired and is no longer available for purchase.
257 """
258 retired: Boolean!
259
260 """
261 This price is subsidized and available to users who cannot pay the standard
262 prices.
263 """
264 subsidized: Boolean!
265 }
266
267 """
268 Price point for a product in a given currency.
269 """
270 type ProductPrice {
271 "Applicable currency for this price"
272 currency: Currency!
273
274 """
275 Price in the smallest denomination of the currency, e.g. cents USD. Does not
276 include any applicable taxes.
277 """
278 amount: Int!
279 }
280
281 """
282 Billing address for invoicing.
283 """
284 type BillingAddress {
285 fullName: String
286 businessName: String
287 address1: String
288 address2: String
289 city: String
290 region: String
291 postcode: String
292 "ISO 3166 two-letter country code"
293 country: Country
294 "Value-added tax number (EU)"
295 vat: String
296 }
297
298 type PaymentMethod {
299 id: Int!
300 created: Time!
301
302 "Currency used with this payment method"
303 currency: Currency!
304
305 "User-friendly name of this payment method (e.g. 'Visa ending in 1234')"
306 name: String!
307
308 "Expiration date of this payment method, if applicable to the type"
309 expires: Time
310 }
311
312 enum SubscriptionStatus {
313 """
314 This subscription is pending and will become active once the first payment is
315 successfully recieved.
316 """
317 PENDING
318 """
319 This subscription is paid but the payment has not settled. Paid services are
320 available while awaiting settlement.
321 """
322 SETTLEMENT
323 """
324 This is the user's active subscription.
325 """
326 ACTIVE
327 """
328 This subscription has been cancelled and the service term is complete.
329 """
330 INACTIVE
331 }
332
333 enum PaymentIntentStatus {
334 PENDING
335 CANCELLED
336 PROCESSING
337 FAILED
338 SUCCEEDED
339 }
340
341 type PaymentOutcome {
342 status: PaymentIntentStatus!
343 error: String
344 }
345
346 type BillingSubscription {
347 id: Int!
348 user: User! @access(scope: PROFILE, kind: RO)
349 created: Time!
350 updated: Time!
351 status: SubscriptionStatus!
352
353 "If true, payment is automatically renewed when term ellapses."
354 autorenew: Boolean!
355
356 currency: Currency!
357 interval: PaymentInterval!
358
359 """
360 Selected product associated with this subscription.
361 """
362 product: Product!
363
364 """
365 Shortcut to get the applicable price point for this subscription's product ID
366 and applicable currency
367 """
368 price: ProductPrice!
369
370 """
371 Total price, not including applicable taxes, in the smallest denomination of
372 the currency, e.g. cents USD.
373 """
374 subtotal: Int!
375
376 """
377 Total price, including applicable taxes, in the smallest denomination of the
378 currency, e.g. cents USD.
379 """
380 total: Int!
381
382 """
383 Status of the last attempted payment for this subscription.
384 """
385 payment: PaymentOutcome!
386 }
387
388 type Invoice {
389 id: Int!
390 invoiceNo: String!
391 issued: Time!
392 entity: Entity! @access(scope: PROFILE, kind: RO)
393
394 product: Product!
395 """Start of service period for which this invoice applies"""
396 serviceStart: Time!
397 """End of service period for which this invoice applies"""
398 serviceEnd: Time!
399
400 currency: Currency!
401 """
402 Amount charged denoted in the smallest denomination of the applicable
403 currency, e.g. cents USD.
404 """
405 total: Int!
406 }
407
408 type OAuthGrant {
409 id: Int!
410 client: OAuthClient!
411 issued: Time!
412 expires: Time!
413 tokenHash: String! @internal
414 grants: String
415 }
416
417 type OAuthGrantRegistration {
418 grant: OAuthGrant!
419 grants: String!
420 secret: String!
421 refreshToken: String!
422 }
423
424 type OAuthClient {
425 id: Int!
426 uuid: String!
427 redirectUrl: String!
428
429 name: String!
430 description: String
431 url: String
432
433 owner: Entity! @access(scope: PROFILE, kind: RO)
434 }
435
436 type OAuthClientRegistration {
437 client: OAuthClient!
438 secret: String!
439 }
440
441 type OAuthPersonalToken {
442 id: Int!
443 issued: Time!
444 expires: Time!
445 comment: String
446 grants: String
447 }
448
449 type OAuthPersonalTokenRegistration {
450 token: OAuthPersonalToken!
451 secret: String!
452 }
453
454 enum WebhookEvent {
455 "Used for user profile webhooks"
456 PROFILE_UPDATE
457 PGP_KEY_ADDED
458 PGP_KEY_REMOVED
459 SSH_KEY_ADDED
460 SSH_KEY_REMOVED
461 }
462
463 interface WebhookSubscription {
464 id: Int!
465 events: [WebhookEvent!]!
466 query: String!
467 url: String!
468
469 """
470 If this webhook was registered by an authorized OAuth 2.0 client, this
471 field is non-null.
472 """
473 client: OAuthClient @private
474
475 "All deliveries which have been sent to this webhook."
476 deliveries(cursor: Cursor): WebhookDeliveryCursor!
477
478 "Returns a sample payload for this subscription, for testing purposes"
479 sample(event: WebhookEvent!): String!
480 }
481
482 type ProfileWebhookSubscription implements WebhookSubscription {
483 id: Int!
484 events: [WebhookEvent!]!
485 query: String!
486 url: String!
487 client: OAuthClient @private
488 deliveries(cursor: Cursor): WebhookDeliveryCursor!
489 sample(event: WebhookEvent!): String!
490 }
491
492 type WebhookDelivery {
493 uuid: String!
494 date: Time!
495 event: WebhookEvent!
496 subscription: WebhookSubscription!
497 requestBody: String!
498
499 """
500 These details are provided only after a response is received from the
501 remote server. If a response is sent whose Content-Type is not text/*, or
502 cannot be decoded as UTF-8, the response body will be null. It will be
503 truncated after 64 KiB.
504 """
505 responseBody: String
506 responseHeaders: String
507 responseStatus: Int
508 }
509
510 interface WebhookPayload {
511 uuid: String!
512 event: WebhookEvent!
513 date: Time!
514 }
515
516 type ProfileUpdateEvent implements WebhookPayload {
517 uuid: String!
518 event: WebhookEvent!
519 date: Time!
520
521 profile: User!
522 }
523
524 type PGPKeyEvent implements WebhookPayload {
525 uuid: String!
526 event: WebhookEvent!
527 date: Time!
528
529 key: PGPKey!
530 }
531
532 type SSHKeyEvent implements WebhookPayload {
533 uuid: String!
534 event: WebhookEvent!
535 date: Time!
536
537 key: SSHKey!
538 }
539
540 """
541 A cursor for enumerating a list of audit log entries
542
543 If there are additional results available, the cursor object may be passed
544 back into the same endpoint to retrieve another page. If the cursor is null,
545 there are no remaining results to return.
546 """
547 type AuditLogCursor {
548 results: [AuditLogEntry!]!
549 cursor: Cursor
550 }
551
552 """
553 A cursor for enumerating a list of invoices
554
555 If there are additional results available, the cursor object may be passed
556 back into the same endpoint to retrieve another page. If the cursor is null,
557 there are no remaining results to return.
558 """
559 type InvoiceCursor {
560 results: [Invoice!]!
561 cursor: Cursor
562 }
563
564 """
565 A cursor for enumerating a list of SSH keys
566
567 If there are additional results available, the cursor object may be passed
568 back into the same endpoint to retrieve another page. If the cursor is null,
569 there are no remaining results to return.
570 """
571 type SSHKeyCursor {
572 results: [SSHKey!]!
573 cursor: Cursor
574 }
575
576 """
577 A cursor for enumerating a list of PGP keys
578
579 If there are additional results available, the cursor object may be passed
580 back into the same endpoint to retrieve another page. If the cursor is null,
581 there are no remaining results to return.
582 """
583 type PGPKeyCursor {
584 results: [PGPKey!]!
585 cursor: Cursor
586 }
587
588 """
589 A cursor for enumerating a list of webhook deliveries
590
591 If there are additional results available, the cursor object may be passed
592 back into the same endpoint to retrieve another page. If the cursor is null,
593 there are no remaining results to return.
594 """
595 type WebhookDeliveryCursor {
596 results: [WebhookDelivery!]!
597 cursor: Cursor
598 }
599
600 """
601 A cursor for enumerating a list of webhook subscriptions
602
603 If there are additional results available, the cursor object may be passed
604 back into the same endpoint to retrieve another page. If the cursor is null,
605 there are no remaining results to return.
606 """
607 type WebhookSubscriptionCursor {
608 results: [WebhookSubscription!]!
609 cursor: Cursor
610 }
611
612 type Query {
613 "Returns API version information."
614 version: Version!
615
616 "Returns the authenticated user."
617 me: User! @access(scope: PROFILE, kind: RO)
618
619 "Returns a specific user"
620 userByName(username: String!): User @access(scope: PROFILE, kind: RO)
621 userByEmail(email: String!): User @access(scope: PROFILE, kind: RO)
622
623 "Returns a specific SSH key by its resource ID."
624 sshKey(rid: ID!): SSHKey @access(scope: SSH_KEYS, kind: RO)
625
626 "Returns a specific PGP key by its resource ID."
627 pgpKey(rid: ID!): PGPKey @access(scope: PGP_KEYS, kind: RO)
628
629 "Returns a specific SSH key by its fingerprint, in hexadecimal"
630 sshKeyByFingerprint(fingerprint: String!): SSHKey @access(scope: SSH_KEYS, kind: RO)
631
632 "Returns a specific PGP key by its fingerprint, in hexadecimal."
633 pgpKeyByFingerprint(fingerprint: String!): PGPKey @access(scope: PGP_KEYS, kind: RO)
634
635 "Returns the audit log for the authenticated user."
636 auditLog(cursor: Cursor): AuditLogCursor! @access(scope: AUDIT_LOG, kind: RO)
637
638 "Returns the authenticated user's login security settings."
639 loginSecurity: LoginSecurity! @access(scope: PROFILE, kind: RO)
640
641 """
642 Returns a list of user profile webhook subscriptions. For clients
643 authenticated with a personal access token, this returns all webhooks
644 configured by all GraphQL clients for your account. For clients
645 authenticated with an OAuth 2.0 access token, this returns only webhooks
646 registered for your client.
647 """
648 profileWebhooks(cursor: Cursor): WebhookSubscriptionCursor!
649
650 "Returns details of a user profile webhook subscription by its ID."
651 profileWebhook(id: Int!): WebhookSubscription
652
653 """
654 Returns information about the webhook currently being processed. This is
655 not valid during normal queries over HTTP, and will return an error if used
656 outside of a webhook context.
657 """
658 webhook: WebhookPayload!
659
660 "Returns the current OAuth grant in use, if any"
661 myOauthGrant: OAuthGrant
662
663 "Returns OAuth grants issued for the authenticated user"
664 oauthGrants: [OAuthGrant!]! @private
665
666 "List of OAuth clients this user administrates"
667 oauthClients: [OAuthClient!]! @private
668
669 "Returns a list of personal OAuth tokens issued"
670 personalAccessTokens: [OAuthPersonalToken!]! @private
671
672 "Returns information about a subscription product available for purchase."
673 product(id: Int!): Product
674
675 "Returns a list of paid subscriptions available for purchase."
676 products: [Product!]!
677
678 ### ###
679 ### The following resolvers are for internal use. ###
680 ### ###
681
682 "Returns a specific user by ID"
683 userByID(id: Int!): User @anoninternal
684
685 "Returns a specific user by username"
686 user(username: String!): User @anoninternal
687
688 "Returns a specific OAuth client (by database ID)"
689 oauthClientByID(id: Int!): OAuthClient @internal
690
691 "Returns a specific OAuth client (by UUID)"
692 oauthClientByUUID(uuid: String!): OAuthClient @internal
693
694 """
695 Returns the revocation status of a given OAuth 2.0 token hash (SHA-512). If
696 the token or client ID has been revoked, this returns true, and the key
697 should not be trusted. Client ID is optional for personal access tokens.
698 """
699 tokenRevocationStatus(hash: String!, clientId: String): Boolean! @internal
700 }
701
702 """
703 Omit these fields to leave them unchanged, or set them to null to clear
704 their value.
705 """
706 input UserInput {
707 url: String
708 location: String
709 bio: String
710 avatar: Upload
711 pronouns: String
712
713 """
714 Note: changing the user's email address will not take effect immediately;
715 the user is sent an email to confirm the change first.
716 """
717 email: String
718 }
719
720 input ProfileWebhookInput {
721 url: String!
722 events: [WebhookEvent!]!
723 query: String!
724 }
725
726 """
727 All fields are optional. If a field is omitted, it is unchanged. If a field is
728 null, it is set to null.
729 """
730 input BillingAddressInput {
731 fullName: String
732 businessName: String
733 address1: String
734 address2: String
735 city: String
736 region: String
737 postcode: String
738 "ISO 3166 two-letter country code"
739 country: Country
740 "Value-added tax number (EU)"
741 vat: String
742 }
743
744 """
745 For changing the active paid subscription's parameters. Changes apply from the
746 start of the next payment term (i.e. from User.paymentDue).
747 """
748 input UpdateBillingSubscriptionInput {
749 productID: Int!
750 interval: PaymentInterval!
751 }
752
753 input ProductPriceInput {
754 currency: Currency!
755 amount: Int!
756 }
757
758 type TOTPConfig {
759 """
760 List of generated recovery codes for use with TOTP.
761 """
762 recoveryCodes: [String!]!
763 }
764
765 type Mutation {
766 updateUser(input: UserInput): User! @access(scope: PROFILE, kind: RW)
767
768 createPGPKey(key: String!): PGPKey! @access(scope: PGP_KEYS, kind: RW)
769 deletePGPKey(id: Int!): PGPKey @access(scope: PGP_KEYS, kind: RW)
770
771 """
772 Creates a new SSH public key from an input as used in the authorized_keys
773 file, see the AUTHORIZED_KEYS FILE FORMAT section in sshd(8). Note that
774 the optional key options are currently discarded.
775 """
776 createSSHKey(key: String!): SSHKey! @access(scope: SSH_KEYS, kind: RW)
777 deleteSSHKey(id: Int!): SSHKey @access(scope: SSH_KEYS, kind: RW)
778
779 """
780 Causes the "last used" time of this SSH key to be set to the current time.
781 """
782 updateSSHKeyLastUsed(fingerprint: String!): SSHKey! @access(scope: SSH_KEYS, kind: RO) @anoninternal
783
784 """
785 Update the authenticated user's billing address.
786 """
787 updateBillingAddress(input: BillingAddressInput!): BillingAddress! @access(scope: BILLING, kind: RW)
788
789 """
790 Update an active billing subscription.
791 """
792 updateBillingSubscription(
793 subscriptionID: Int!,
794 input: UpdateBillingSubscriptionInput!,
795 ): BillingSubscription @access(scope: BILLING, kind: RW)
796
797 """
798 Cancels an active billing subscription. The changes will not take effect
799 until the end of the paid term (unless the account is past due, in which case
800 it applies immediately).
801 """
802 cancelBillingSubscription(
803 subscriptionID: Int!,
804 ): BillingSubscription @private
805
806 # TODO: Allow removal of the last payment method if the user has disabled
807 # automatic renewal (blocker: allow users to disable autorenew)
808 """
809 Removes a payment method from your account. Cannot be used to remove the last
810 payment method.
811 """
812 deletePaymentMethod(id: Int!): PaymentMethod @access(scope: BILLING, kind: RW)
813
814 """
815 Sets the user's default payment method.
816 """
817 setDefaultPaymentMethod(id: Int!): PaymentMethod @access(scope: BILLING, kind: RW)
818
819 """
820 Creates a new user profile webhook subscription. When an event from the
821 provided list of events occurs, the 'query' parameter (a GraphQL query)
822 will be evaluated and the results will be sent to the provided URL as the
823 body of an HTTP POST request. The list of events must include at least one
824 event, and no duplicates.
825
826 This query is evaluated in the webhook context, such that query { webhook }
827 may be used to access details of the event which trigged the webhook. The
828 query may not make any mutations.
829 """
830 createWebhook(config: ProfileWebhookInput!): WebhookSubscription!
831
832 """
833 Deletes a user profile webhook. Any events already queued may still be
834 delivered after this request completes. Clients authenticated with a
835 personal access token may delete any webhook registered for their account,
836 but authorized OAuth 2.0 clients may only delete their own webhooks.
837 Manually deleting a webhook configured by a third-party client may cause
838 unexpected behavior with the third-party integration.
839 """
840 deleteWebhook(id: Int!): WebhookSubscription!
841
842 ### ###
843 ### The following resolvers are for admin use. ###
844 ### ###
845
846 """
847 Transfers billing details from one user account to another, returning the
848 target account.
849 """
850 billingTransfer(from: String!, to: String!): User! @admin
851
852 """
853 Grants free service to the given user ID until the provided expiration date.
854 """
855 subsidizeUser(userID: Int!, until: Time!): User! @admin
856
857 """
858 Create a new paid product.
859 """
860 createProduct(name: String!, prices: [ProductPriceInput!]!): Product! @admin
861
862 """
863 Retires a paid product.
864 """
865 retireProduct(id: Int!): Product @admin
866
867 ### ###
868 ### The following resolvers are for internal use. ###
869 ### ###
870
871 "Registers a new account."
872 registerAccount(email: String!,
873 username: String!,
874 password: String!,
875 pgpKey: String): User @anoninternal
876
877 "Requests a password reset. The return value is meaningless."
878 resetPassword(email: String!): Int @anoninternal
879
880 "Confirm an account registration email."
881 confirmRegistration(token: String!): User @anoninternal
882
883 "Confirm a user's change of email address"
884 confirmEmailChange(token: String!): User @anoninternal
885
886 "Confirm a user's password change"
887 confirmPasswordChange(
888 token: String!,
889 newPassword: String!,
890 ): User @anoninternal
891
892 """
893 Enables TOTP for the user account. The secret is 20 base32-encoded bytes.
894 """
895 enableTOTP(secret: String!): TOTPConfig! @internal
896
897 # TODO:
898 # - Enable TOTP via GraphQL as well
899 # - Manage logins and authentication through GraphQL more generally
900
901 """
902 Registers an OAuth client. Only OAuth 2.0 confidental clients are
903 supported.
904 """
905 registerOAuthClient(
906 redirectUri: String!,
907 clientName: String!,
908 clientDescription: String,
909 clientUrl: String): OAuthClientRegistration! @internal
910
911 """
912 Revokes this OAuth client, revoking all tokens for it and preventing future
913 use.
914 """
915 revokeOAuthClient(uuid: String!): OAuthClient @internal
916
917 "Revokes a specific OAuth grant."
918 revokeOAuthGrant(hash: String!): OAuthGrant @internal
919
920 "Issues an OAuth personal access token."
921 issuePersonalAccessToken(grants: String, comment: String):
922 OAuthPersonalTokenRegistration! @internal
923
924 "Revokes a personal access token."
925 revokePersonalAccessToken(id: Int!): OAuthPersonalToken @internal
926
927 """
928 Issues an OAuth 2.0 authorization code. Used after the user has consented
929 to the access grant request.
930 """
931 issueAuthorizationCode(clientUUID: String!, grants: String!): String! @internal
932
933 """
934 Completes the OAuth 2.0 grant process and issues an OAuth token for a
935 specific OAuth client.
936 """
937 issueOAuthGrant(authorization: String!, clientUUID: String,
938 clientSecret: String!, redirectUri: String): OAuthGrantRegistration @internal
939
940 """
941 Refreshes an existing OAuth 2.0 grant. This invalidates the previous grant
942 and returns a new one.
943 """
944 refreshOAuthGrant(refreshToken: String!, clientUUID: String!,
945 clientSecret: String!, grants: String): OAuthGrantRegistration @internal
946
947 """
948 Send a notification email.
949
950 The 'address' parameter must be a single RFC 5322 address (e.g. "Barry Gibbs
951 <[email protected]>", or "[email protected]"). The 'message' parameter must be a
952 RFC 5322 compliant Internet message with the special requirement that it must
953 not contain any recipients (i.e. no 'To', 'Cc', or 'Bcc' header).
954
955 The message will be signed with the site key. If the address is that of a
956 registered user it will be encrypted according to the user's privacy
957 settings.
958 """
959 sendEmail(address: String!, message: String!): Boolean! @anoninternal
960
961 """
962 Deletes the authenticated user's account.
963 """
964 deleteUser(reserve: Boolean!): Int! @internal
965
966 """
967 Orders a new paid product subscription. The new subscription is in a PENDING
968 state. The payment intent should be completed to proceed.
969 """
970 orderProductSubscription(
971 productID: Int!,
972 currency: Currency!,
973 interval: PaymentInterval!,
974 autorenew: Boolean!,
975 """
976 Optional: update the user's billing address at the same time
977 """
978 address: BillingAddressInput,
979 """
980 Optional: include this if retrying the same request
981 """
982 idempotencyKey: String,
983 ): PaymentIntent @internal
984
985 """
986 Creates a new payment intent to charge a subscription's renewal fee
987 interactively. The subscription must be past due.
988 """
989 beginSubscriptionRenewal(
990 subscriptionID: Int!,
991 """
992 Optional: include this if retrying the same request
993 """
994 idempotencyKey: String,
995 ): PaymentIntent! @internal
996
997 """
998 Finalizes a product order from the PaymentIntent ID after the user has
999 finalized their payment, returning the completed PaymentIntent.
1000 """
1001 finalizePaymentIntent(intentID: String!): PaymentIntent! @internal
1002
1003 """
1004 Creates a "setup" intent for adding a new payment method to the authenticated
1005 user's account.
1006 """
1007 createSetupIntent: SetupIntent! @internal
1008
1009 """
1010 Finalizes a setup intent.
1011 """
1012 finalizeSetupIntent(intentID: String!): SetupIntent @internal
1013
1014 """
1015 Processes payment when the user's account is past due. Returns the payment
1016 intent if a payment was collected, or null if a payment was not collected but
1017 the operation was successful (the latter occurs when a subscription was
1018 cancelled or a subsidized user's subsidy expired, in these cases the account
1019 is settled and converted to non-paying).
1020 """
1021 processPaymentDue: PaymentIntent @internal
1022
1023 """
1024 Causes an invoice to be regenerated in order to issue a correction. The admin
1025 is assumed to have manually made the required changes in the database.
1026 """
1027 reissueInvoice(id: Int!): Invoice @admin
1028 }
1029
1030 # The following types are for internal use
1031
1032 interface PaymentIntent {
1033 id: String!
1034 subscription: BillingSubscription!
1035 billingAddress: BillingAddress!
1036 idempotencyKey: String!
1037
1038 taxRate: Float
1039 taxDue: Int!
1040 totalDue: Int!
1041
1042 method: PaymentMethod
1043 outcome: PaymentOutcome
1044 }
1045
1046 type StripePaymentIntent implements PaymentIntent {
1047 id: String!
1048 subscription: BillingSubscription!
1049 billingAddress: BillingAddress!
1050 idempotencyKey: String!
1051
1052 totalDue: Int!
1053 taxRate: Float
1054 taxDue: Int!
1055
1056 method: PaymentMethod
1057 outcome: PaymentOutcome
1058
1059 publicKey: String
1060 clientSecret: String
1061 }
1062
1063 enum SetupIntentStatus {
1064 PENDING
1065 PROCESSING
1066 SUCCEEDED
1067 CANCELLED
1068 }
1069
1070 interface SetupIntent {
1071 id: String!
1072 status: SetupIntentStatus!
1073 method: PaymentMethod
1074 }
1075
1076 type StripeSetupIntent implements SetupIntent {
1077 id: String!
1078 status: SetupIntentStatus!
1079 method: PaymentMethod
1080
1081 publicKey: String
1082 clientSecret: String
1083 }